ava.node_cli.txt

                                  ┏━━━━━━━━━┓
                                  ┃   AVA   ┃
                                  ┗━━━━━━━━━┛

ALTERNATIVES ==>                  #See Mocha

VERSION ==>                       #6.2.0
                                  #Node or CLI

REPORTERS ==>                     #See ava reporters doc
ASSERTIONS ==>                    #See ava assertions doc
DIFF TESTING ==>                  #See ava snapshots doc

GLOB                              #Uses multimatch, i.e. can use '!...'

                                  ┌───────────┐
                                  │   TESTS   │
                                  └───────────┘

AVA                               #Should be named "test"

AVA('TEST_TITLE', TFUNC(TEST))    #Define a test
                                  #Thrown exceptions and rejectes promises make test fail.
                                  #'TEST_TITLE' must be unique for each test file

ASYNC ==>                         #Using TFUNC()->PROMISE|OBSERVABLE

AVA('TEST_TITLE',                 #Pass TARGS to TFUNC()
 TFUNC(TEST, TARGS...), TARGS...) #Meant for data-driven testing

TFUNC.title('TEST_TITLE',TARGS...)#Can be overriden to set 'TEST_TITLE' according to arguments
 ->'TEST_TITLE'                   #Only works when data-driven testing is used
                                  #Can then use AVA(TFUNC, ...): i.e. skip 'TEST_TITLE'

TEST.plan(NUM)                    #

AVA.meta.file                     #import.meta.url of top-level test file

                                  ┌───────────────────┐
                                  │   ORCHESTRATION   │
                                  └───────────────────┘

AVA.before|after(...)             #Before|after all, for current test file
                                  #Same signature and async as tests
AVA.before|afterEach(...)         #Before|after each test, for current test file
                                  #Same signature and async as tests
AVA.after[Each].always(...)       #Same but also runs even if there were test failures

TEST.teardown(FUNC()[->>])        #Run when TEST finishes, whether failed or not

registerCompletionHandler(FUNC()) #Run when all TESTs finished, whether failed or not

TEST.context                      #OBJ:
                                  #  - before(): initialized to {}
                                  #  - beforeEach(): shallow cloned from before()
                                  #  - beforeEach|test|afterEach(): shared by reference
                                  #  - after(): reference from before()
TEST.passed                       #BOOL

SHARED WORKERS ==>                #Way to share state and logic between test files
                                  #To document only if I need it

                                  ┌────────────┐
                                  │   CONFIG   │
                                  └────────────┘

CONF ==>                          #Can be:
                                  #  - --config CONF_FILE
                                  #  - package.json "ava" CONF_OBJ
                                  #  - [...]/ava.config.js|cjs|mjs CONF_FILE
                                  #  - ava --FLAG: only the ones documented below, unless possible only through package.json
                                  #CONF_FILE should export [PROMISE_]CONF_OBJ[()]

--init                            #npm install -D ava, then add npm script "npm test: ava"

                                  ┌───────────────┐
                                  │   SELECTION   │
                                  └───────────────┘

ava [GLOB...]                     #Def: [src|source/]test.js|cjs|mjs, test-*.js|cjs|mjs, *.test|spec.js|cjs|mjs or test[s]|__tests__/**/*.js|cjs|mjs
--files GLOB                      #Always exclude:
CONF.files                        #  - node_modules
                                  #  - _*
                                  #  - test|tests|__tests__/**/_*|helper[s]|fixture[s]
                                  #GLOB can be DIR
                                  #GLOB can be suffixed with ':START[-END],...' to only run specific files (like AVA.only())

CONF.extensions                   #'EXT'_ARR (def: ['js', 'mjs', 'cjs'])
                                  #If CONF.configurableModuleFormat true, is an OBJ instead, with OBJ.EXT:
                                  #  - 'commonjs'
                                  #  - 'module'
                                  #  - true (def): 'module' for 'mjs', 'commonjs' otherwise
CONF.configurableModuleFormat     #BOOL (def: false)

--require FILE                    #'FILE'[_ARR] or ['FILE', ...ARGS]_ARR to import() first
CONF.require                      #FILE's default export can be a FUNC(...ARGS)->>
                                  #ARGS are copied using structuredClone()
                                  #Can be TypeScript

--match|m GLOB                    #Only run tests with matching TEST_TITLE
                                  #Can be done several times

AVA.skip(...)                     #Skip that test.
AVA.todo(...)                     #Skip that test. FUNC must not be defined

AVA.only(...)                     #Only run this test
                                  #Only for current file

AVA.failing(...)                  #Make test pass if it fails (but reported as "known failure" by default reporter)
                                  #Make test fail if it passes.
                                  #Meant as temporary until test is fixed

                                  ┌───────────────┐
                                  │   EXECUTION   │
                                  └───────────────┘

--fail-fast                       #Stop all tests on first test failure

--watch|w                         #Watch mode (using Chokidar, see its doc)
                                  #Can be re-run by typing r
                                  #Can run --update-snapshots by typing u
CONF.watchMode.ignoreChanges      #'GLOB'_ARR that do not trigger re-run in watch mode
                                  #CONF.files|sources must target regular files (not directories).

CONF.environmentVariables         #OBJ of ENVVARs to set

                                  ┌───────────┐
                                  │   DEBUG   │
                                  └───────────┘

ava debug FILE.js                 #Run with --inspect
--host HOST                       #

                                  ┌───────────────┐
                                  │   REPORTING   │
                                  └───────────────┘

TEST.log(...)                     #Like console.log(...) but indented for that test, and only shown on failure
                                  #In TAP output, is unknown line prepended by '  * '

--[no-]color                      #

                                  ┌───────────┐
                                  │   SPEED   │
                                  └───────────┘

TEST.timeout(NUM[, 'MESSAGE'])    #As opposed to other test runners, timeout is reset to 0 each time another concurrent test ends
--timeout|T NUM|STR               #NUM is in ms, STR ends with 's|ms'
                                  #Def: '10s'
TEST.timeout.clear()              #Undo

                                  ┌─────────────────┐
                                  │   PARALLELISM   │
                                  └─────────────────┘

--concurrency|c NUM               #CPU parallelism: run test files in parallel, in different worker threads, with maximum NUM worker threads at once
                                  #Def NUM: number of CPUs, or 2 if CI (using `ci-info`)
CONF.workerThreads                #BOOL (def: true). Use worker threads for each test file instead of processes
                                  #When false, and running lots of tests at once, sometimes get strange "tests remaining" bug
CONF.filterNodeArguments          #FUNC('--FLAG')->BOOL, filtering Node CLI flags when using CONF.workerThreads true
 ForWorkerThreads                 #Meant to exclude CLI flags that do not work in threads, e.g. --expose-gc

I/O PARALLELISM ==>               #Tests within a specific test file are run in parallel.
AVA.serial[.before|skip|...](...) #Make this test serial instead
--serial|s                        #Make all tests serial instead
                                  #Also implies --concurrency 1

--utilizeParallelBuilds           #If true (def), and currently run in multi-nodes CI, automatically uses CPU parallelism

                                  ┌─────────────┐
                                  │   LINTING   │
                                  └─────────────┘

VERSION ==>                      ##Module eslint-plugin-ava (15.0.1)
                                 ##There is a recommended set with all rules errors except:
                                 ##  - off: max-asserts and prefer-power-assert
                                 ##  - warn: no-todo-test

ava/no-unknown-modifiers         ##No typos in AVA.*() or assertion function names
ava/use-t-well                   ##Avoid typos in TEST.*()
ava/no-todo-implementation       ##AVA.todo() should not define any TFUNC
ava/no-nested-tests              ##No nested tests
ava/no-duplicate-modifiers       ##No duplicate modifiers like AVA.only.only()
ava/assertion-arguments [OBJ]    ##Correct number of arguments to assertions
                                 ##OBJ: message 'always|never': must [not] specify 'ASSERT_TITLE'

ava/test-title                   ##Must set a 'TEST_TITLE'
                                 ##Only if multiple tests in current file
ava/no-identical-title           ##No duplicate 'TEST_TITLE'
ava/test-title-format [OBJ]      ##'TEST_TITLE' must match OBJ.format 'REGEXP'

ava/no-ignored-test-files [OBJ]  ##Must not define tests outside CONF.files
                                 ##OBJ (def: taken from ava CONF)
                                 ##  - files 'GLOB'_ARR
                                 ##  - helpers 'GLOB'_ARR
                                 ##  - extensions STR_ARR
ava/no-import-test-files         ##Must not import tests from CONF.files
                                 ##Same OBJ as ava/no-ignored-test-files: files|extensions

ava/no-only-test                 ##No AVA.only()
ava/no-skip-test                 ##No AVA.skip()
ava/no-skip-assert               ##No ASSERT.skip()
ava/no-todo-test                 ##No AVA.todo()

ava/hooks-order                  ##Should follow order: before(), after(), after.always(), beforeEach(), afterEach(), afterEach.always(), test()

ava/no-inline-assertions         ##test(STR, t => { EXPR }) instead of test(STR, t => EXPR)

ava/max-asserts [NUM]            ##Max number of assertions per test

ava/use-true-false               ##Use TEST.true|false(BOOL) instead of TEST.truthy|falsy(BOOL)
ava/prefer-t-regex               ##Use TEST.regexp() instead of REGEXP.test() and STR.match|search()
ava/prefer-power-assert          ##Use TEST.assert()
ava/no-incorrect-deep-equal      ##No TEST.[not]deepEqual() with primitive types

ava/use-t                        ##TEST must be named "t"
ava/use-test                     ##AVA must be named "test"

ava/prefer-async-await           ##Prefer async|await over PROMISE
ava/no-async-fn-without-await    ##Must use await inside async FUNC
ava/use-t-throws-async-well      ##Must use await in front of t.[not]throwsAsync()

                                  ┌────────────────┐
                                  │   TYPESCRIPT   │
                                  └────────────────┘

@ava/typescript                   #Version 5.0.0
CONF.typescript                   #When defined, use transpiled files for source, but source files for stack traces.
CONF.typescript.rewritePaths      #OBJ:
                                  #  - key is source dir (e.g. 'src/')
                                  #  - value is transpiled dir (e.g. 'build/src/')
CONF.typescript.extensions        #'EXT'_ARR. For example for JSX support ['ts', 'tsx']
CONF.typescript.compile           #Either false (def, noop) or 'tsc' (run 'tsc' at beginning)