ava.config.js

@@ -4,7 +4,9 @@ const skipWatchMode = process.env.TEST_AVA_SKIP_WATCH_MODE ? ['!test/watch-mode/
 
 export default { // eslint-disable-line import/no-anonymous-default-export
 	files: ['test/**', '!test/**/{fixtures,helpers}/**', ...skipWatchMode],
-	ignoredByWatcher: ['{coverage,docs,media,test-types,test-tap}/**'],
+	watchMode: {
+		ignoreChanges: ['{coverage,docs,media,test-types,test-tap}/**'],
+	},
 	environmentVariables: {
 		AVA_FAKE_SCM_ROOT: '.fake-root', // This is an internal test flag.
 	},

docs/01-writing-tests.md

@@ -10,7 +10,7 @@ AVA tries to run test files with their current working directory set to the dire
 
 ## Test isolation
 
-Each test file is run in a new worker thread. This is new as of AVA 4, though you can fall back to AVA 3's behavior of running in separate processes.
+By default each test file is run in a new worker thread. You can fall back running in separate processes.
 
 AVA will set `process.env.NODE_ENV` to `test`, unless the `NODE_ENV` environment variable has been set. This is useful if the code you're testing has test defaults (for example when picking what database to connect to). It may cause your code or its dependencies to behave differently though. Note that `'NODE_ENV' in process.env` will always be `true`.
 
@@ -154,7 +154,7 @@ AVA lets you register hooks that are run before and after your tests. This allow
 
 If a test is skipped with the `.skip` modifier, the respective `.beforeEach()`, `.afterEach()` and `.afterEach.always()` hooks are not run. Likewise, if all tests in a test file are skipped `.before()`, `.after()` and `.after.always()` hooks for the file are not run.
 
-*You may not need to use `.afterEach.always()` hooks to clean up after a test.* You can use [`t.teardown()`](./02-execution-context.md#tteardownfn) to undo side-effects *within* a particular test.
+*You may not need to use `.afterEach.always()` hooks to clean up after a test.* You can use [`t.teardown()`](./02-execution-context.md#tteardownfn) to undo side-effects *within* a particular test. Or use [`registerCompletionHandler()`](./08-common-pitfalls.md#timeouts-because-a-file-failed-to-exit) to run cleanup code after AVA has completed its work.
 
 Like `test()` these methods take an optional title and an implementation function. The title is shown if your hook fails to execute. The implementation is called with an [execution object](./02-execution-context.md). You can use assertions in your hooks. You can also pass a [macro function](#reusing-test-logic-through-macros) and additional arguments.
 

docs/03-assertions.md

@@ -21,13 +21,11 @@ test('unicorns are truthy', t => {
 
 If multiple assertion failures are encountered within a single test, AVA will only display the *first* one.
 
-In AVA 6, assertions return `true` if they've passed and throw otherwise. Catching this error does not cause the test to pass. The error value is undocumented.
-
-In AVA 5, assertions return a boolean and do not throw. You can use this to return early from a test. The `snapshot()` assertion does not return a value.
+Assertions return `true` if they've passed and throw otherwise. Catching this error does not cause the test to pass. The error value is undocumented.
 
 If you use TypeScript you can use some assertions as type guards.
 
-Note that the "throws" assertions return the error that was thrown (provided the assertion passed). In AVA 5, they return `undefined` if the assertion failed.
+Note that the "throws" assertions return the error that was thrown (provided the assertion passed).
 
 ## Assertion planning
 
@@ -179,7 +177,7 @@ t.like([1, 2, 3, 4], [1, , 3])
 Assert that an error is thrown. `fn` must be a function which should throw. By default, the thrown value *must* be an error. It is returned so you can run more assertions against it.
 `expectation` can be an object with one or more of the following properties:
 
-* `any`: a boolean only available in AVA 6, if `true` then the thrown value does not need to be an error. Defaults to `false`
+* `any`: a boolean, if `true` then the thrown value does not need to be an error. Defaults to `false`
 * `instanceOf`: a constructor, the thrown error must be an instance of
 * `is`: the thrown error must be strictly equal to `expectation.is`
 * `message`: the following types are valid:
@@ -214,7 +212,7 @@ Assert that an error is thrown. `thrower` can be an async function which should
 By default, the thrown value *must* be an error. It is returned so you can run more assertions against it.
 `expectation` can be an object with one or more of the following properties:
 
-* `any`: a boolean only available in AVA 6, if `true` then the thrown value does not need to be an error. Defaults to `false`
+* `any`: a boolean, if `true` then the thrown value does not need to be an error. Defaults to `false`
 * `instanceOf`: a constructor, the thrown error must be an instance of
 * `is`: the thrown error must be strictly equal to `expectation.is`
 * `message`: the following types are valid:
@@ -279,7 +277,7 @@ Compares the `expected` value with a previously recorded snapshot. Snapshots are
 
 The implementation function behaves the same as any other test function. You can even use macros. The first title argument is always optional. Additional arguments are passed to the implementation or macro function.
 
-`.try()` is an asynchronous function. You must `await` it. The result object has `commit()` and `discard()` methods. You must decide whether to commit or discard the result. If you commit a failed result, your test will fail. In AVA 6, calling `commit()` on a failed result will throw an error.
+`.try()` is an asynchronous function. You must `await` it. The result object has `commit()` and `discard()` methods. You must decide whether to commit or discard the result. If you commit a failed result, your test will fail. Calling `commit()` on a failed result will throw an error.
 
 You can check whether the attempt passed using the `passed` property. Any assertion errors are available through the `errors` property. The attempt title is available through the `title` property.
 

docs/07-test-timeouts.md

@@ -4,7 +4,7 @@ Translations: [Français](https://github.com/avajs/ava-docs/blob/main/fr_FR/docs
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/avajs/ava/tree/main/examples/timeouts?file=test.js&terminal=test&view=editor)
 
-Timeouts in AVA behave differently than in other test frameworks. AVA resets a timer after each test, forcing tests to quit if no new test results were received within the specified timeout. This can be used to handle stalled tests.
+Timeouts in AVA behave differently than in other test frameworks. AVA resets a timer after each test, forcing tests to quit if no new test results were received within the specified timeout. This can be used to handle stalled tests. This same mechanism is used to determine when a test file is preventing a clean exit.
 
 The default timeout is 10 seconds.
 

docs/08-common-pitfalls.md

@@ -81,6 +81,37 @@ Error [ERR_WORKER_INVALID_EXEC_ARGV]: Initiated Worker with invalid execArgv fla
 
 If possible don't specify the command line option when running AVA. Alternatively you could [disable worker threads in AVA](./06-configuration.md#options).
 
+## Timeouts because a file failed to exit
+
+You may get a "Timed out while running tests" error because AVA failed to exit when running a particular file.
+
+AVA waits for Node.js to exit the worker thread or child process. If this takes too long, AVA counts it as a timeout.
+
+It is best practice to make sure your code exits cleanly. We've also seen occurrences where an explicit `process.exit()` call inside a worker thread could not be observed in AVA's main process.
+
+For these reasons we're not providing an option to disable this timeout behavior. However, it is possible to register a callback for when AVA has completed the test run without uncaught exceptions or unhandled rejections. From inside this callback you can do whatever you need to do, including calling `process.exit()`.
+
+Create a `_force-exit.mjs` file:
+
+```js
+import process from 'node:process';
+import { registerCompletionHandler } from 'ava';
+
+registerCompletionHandler(() => {
+	process.exit();
+});
+```
+
+Completion handlers are invoked in order of registration. Results are not awaited.
+
+Load it for all test files through AVA's `require` option:
+
+```js
+export default {
+	require: ['./_force-exit.mjs'],
+};
+```
+
 ## Sharing variables between asynchronous tests
 
 By default AVA executes tests concurrently. This can cause problems if your tests are asynchronous and share variables.

docs/recipes/typescript.md

@@ -177,7 +177,7 @@ Note that, despite the type cast above, when executing `t.context` is an empty o
 
 ## Typing `throws` assertions
 
-In AVA 6, the `t.throws()` and `t.throwsAsync()` assertions are typed to always return an `Error`. You can customize the error class using generics:
+The `t.throws()` and `t.throwsAsync()` assertions are typed to always return an `Error`. You can customize the error class using generics:
 
 ```ts
 import test from 'ava';
@@ -206,6 +206,4 @@ test('throwsAsync', async t => {
 });
 ```
 
-In AVA 5, the assertion is typed to return the `Error` if the assertion passes *or* `undefined` if it fails.
-
 [`@ava/typescript`]: https://github.com/avajs/typescript

docs/recipes/watch-mode.md

@@ -16,17 +16,13 @@ Please note that integrated debugging and the TAP reporter are unavailable when
 
 ## Requirements
 
-AVA 5 uses [`chokidar`] as the file watcher. Note that even if you see warnings about optional dependencies failing during install, it will still work fine. Please refer to the *[Install Troubleshooting]* section of `chokidar` documentation for how to resolve the installation problems with chokidar.
-
-Otherwise, AVA 6 uses `fs.watch()`. Support for `recursive` mode is required. Note that this has only become available on Linux since Node.js 20. [Other caveats apply](https://nodejs.org/api/fs.html#caveats), for example this won't work well on network filesystems and Docker host mounts.
+AVA uses `fs.watch()`. Support for `recursive` mode is required. Note that this has only become available on Linux since Node.js 20. [Other caveats apply](https://nodejs.org/api/fs.html#caveats), for example this won't work well on network filesystems and Docker host mounts.
 
 ## Ignoring changes
 
 By default AVA watches for changes to all files, except for those with a `.snap.md` extension, `ava.config.*` and files in [certain directories](https://github.com/novemberborn/ignore-by-default/blob/master/index.js) as provided by the [`ignore-by-default`] package.
 
-With AVA 5, you can configure additional patterns for files to ignore in the [`ava` section of your `package.json`, or `ava.config.*` file][config], using the `ignoredByWatcher` key.
-
-With AVA 6, place these patterns within the `watchMode` object:
+You can configure additional patterns for files to ignore in the [`ava` section of your `package.json`, or `ava.config.*` file][config], using the `ignoreChanges` key within the `watchMode` object:
 
 ```js
 export default {
@@ -42,9 +38,7 @@ If your tests write to disk they may trigger the watcher to rerun your tests. Co
 
 AVA tracks which source files your test files depend on. If you change such a dependency only the test file that depends on it will be rerun. AVA will rerun all tests if it cannot determine which test file depends on the changed source file.
 
-AVA 5 spies on `require()` calls to track dependencies. Custom extensions and transpilers are supported, provided you [added them in your `package.json` or `ava.config.*` file][config], and not from inside your test file.
-
-With AVA 6, dependency tracking works for `require()` and `import` syntax, as supported by [@vercel/nft](https://github.com/vercel/nft). `import()` is supported but dynamic paths such as `import(myVariable)` are not.
+Dependency tracking works for `require()` and `import` syntax, as supported by [@vercel/nft](https://github.com/vercel/nft). `import()` is supported but dynamic paths such as `import(myVariable)` are not.
 
 Files accessed using the `fs` module are not tracked.
 

entrypoints/internal.d.mts

@@ -1,4 +1,4 @@
-import type {StateChangeEvent} from '../types/state-change-events.d';
+import type {StateChangeEvent} from '../types/state-change-events.d.cts';
 
 export type Event = StateChangeEvent;
 

entrypoints/main.d.mts

@@ -10,3 +10,11 @@ declare const test: TestFn;
 
 /** Call to declare a test, or chain to declare hooks or test modifiers */
 export default test;
+
+/**
+ * Register a function to be called when AVA has completed a test run without uncaught exceptions or unhandled rejections.
+ *
+ * Completion handlers are invoked in order of registration. Results are not awaited.
+ */
+declare const registerCompletionHandler: (handler: () => void) => void;
+export {registerCompletionHandler};

entrypoints/main.mjs

@@ -1 +1,2 @@
 export {default} from '../lib/worker/main.cjs';
+export {registerCompletionHandler} from '../lib/worker/completion-handlers.js';

lib/api.js

@@ -303,7 +303,9 @@ export default class Api extends Emittery {
 			// Allow shared workers to clean up before the run ends.
 			await Promise.all(deregisteredSharedWorkers);
 			const files = scheduler.storeFailedTestFiles(runStatus, this.options.cacheEnabled === false ? null : this._createCacheDir());
-			runStatus.emitStateChange({type: 'touched-files', files});
+			if (files) {
+				runStatus.emitStateChange({type: 'touched-files', files});
+			}
 		} catch (error) {
 			runStatus.emitStateChange({type: 'internal-error', err: serializeError(error)});
 		}