ava 5.3.1 → 6.0.0

package/types/assertions.d.cts

@@ -1,12 +1,15 @@
 export type ErrorConstructor<ErrorType extends Error = Error> = {
-	new (...args: any[]): ErrorType;
 	readonly prototype: ErrorType;
-}
+	new (...args: any[]): ErrorType;
+};
 
 export type ThrownError<ErrorType extends ErrorConstructor | Error> = ErrorType extends ErrorConstructor ? ErrorType['prototype'] : ErrorType;
 
 /** Specify one or more expectations the thrown error must satisfy. */
 export type ThrowsExpectation<ErrorType extends ErrorConstructor | Error> = {
+	/** If true, the thrown error is not required to be a native error. */
+	any?: false;
+
 	/** The thrown error must have a code that equals the given string or number. */
 	code?: string | number;
 
@@ -23,10 +26,23 @@ export type ThrowsExpectation<ErrorType extends ErrorConstructor | Error> = {
 	name?: string;
 };
 
+export type ThrowsAnyExpectation = Omit<ThrowsExpectation<any>, 'any' | 'instanceOf' | 'is'> & {
+	/** If true, the thrown error is not required to be a native error. */
+	any: true;
+
+	/** The thrown error must be an instance of this constructor. */
+	instanceOf?: new (...args: any[]) => any;
+
+	/** The thrown error must be strictly equal to this value. */
+	is?: any;
+};
+
 export type Assertions = {
 	/**
 	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
 	 * indicating whether the assertion passed.
+	 *
+	 * Note: An `else` clause using this as a type guard will be subtly incorrect for `string` and `number` types and will not give `0` or `''` as a potential value in an `else` clause.
 	 */
 	assert: AssertAssertion;
 
@@ -103,12 +119,12 @@ export type Assertions = {
 	snapshot: SnapshotAssertion;
 
 	/**
-	 * Assert that the function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error value.
+	 * Assert that the function throws a native error. If so, returns the error value.
 	 */
 	throws: ThrowsAssertion;
 
 	/**
-	 * Assert that the async function throws [an error](https://www.npmjs.com/package/is-error), or the promise rejects
+	 * Assert that the async function throws a native error, or the promise rejects
 	 * with one. If so, returns a promise for the error value, which must be awaited.
 	 */
 	throwsAsync: ThrowsAsyncAssertion;
@@ -121,16 +137,24 @@ export type Assertions = {
 	/**
 	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
 	 * indicating whether the assertion passed.
+	 *
+	 * Note: An `else` clause using this as a type guard will be subtly incorrect for `string` and `number` types and will not give `0` or `''` as a potential value in an `else` clause.
 	 */
 	truthy: TruthyAssertion;
 };
 
+type FalsyValue = false | 0 | 0n | '' | null | undefined; // eslint-disable-line @typescript-eslint/ban-types
+type Falsy<T> = T extends Exclude<T, FalsyValue> ? (T extends number | string | bigint ? T & FalsyValue : never) : T;
+
 export type AssertAssertion = {
 	/**
-	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
-	 * indicating whether the assertion passed.
+	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning `true` if the
+	 * assertion passed and throwing otherwise.
+	 *
+	 * Note: An `else` clause using this as a type guard will be subtly incorrect for `string` and `number` types and will
+	 * not give `0` or `''` as a potential value in an `else` clause.
 	 */
-	(actual: any, message?: string): boolean;
+	<T>(actual: T, message?: string): actual is T extends Falsy<T> ? never : T;
 
 	/** Skip this assertion. */
 	skip(actual: any, message?: string): void;
@@ -139,19 +163,19 @@ export type AssertAssertion = {
 export type DeepEqualAssertion = {
 	/**
 	 * Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
-	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 * `expected`, returning `true` if the assertion passed and throwing otherwise.
 	 */
 	<Actual, Expected extends Actual>(actual: Actual, expected: Expected, message?: string): actual is Expected;
 
 	/**
 	 * Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
-	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 * `expected`, returning `true` if the assertion passed and throwing otherwise.
 	 */
 	<Actual extends Expected, Expected>(actual: Actual, expected: Expected, message?: string): expected is Actual;
 
 	/**
 	 * Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
-	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 * `expected`, returning `true` if the assertion passed and throwing otherwise.
 	 */
 	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): boolean;
 
@@ -161,7 +185,7 @@ export type DeepEqualAssertion = {
 
 export type LikeAssertion = {
 	/**
-	 * Assert that `value` is like `selector`, returning a boolean indicating whether the assertion passed.
+	 * Assert that `value` is like `selector`, returning `true` if the assertion passed and throwing otherwise.
 	 */
 	<Expected extends Record<string, any>>(value: any, selector: Expected, message?: string): value is Expected;
 
@@ -170,8 +194,8 @@ export type LikeAssertion = {
 };
 
 export type FailAssertion = {
-	/** Fail the test, always returning `false`. */
-	(message?: string): boolean;
+	/** Fail the test. */
+	(message?: string): never;
 
 	/** Skip this assertion. */
 	skip(message?: string): void;
@@ -179,7 +203,7 @@ export type FailAssertion = {
 
 export type FalseAssertion = {
 	/**
-	 * Assert that `actual` is strictly false, returning a boolean indicating whether the assertion passed.
+	 * Assert that `actual` is strictly false, returning `true` if the assertion passed and throwing otherwise.
 	 */
 	(actual: any, message?: string): actual is false;
 
@@ -189,10 +213,10 @@ export type FalseAssertion = {
 
 export type FalsyAssertion = {
 	/**
-	 * Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), returning a boolean
-	 * indicating whether the assertion passed.
+	 * Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), returning `true` if the
+	 * assertion passed and throwing otherwise.
 	 */
-	(actual: any, message?: string): boolean;
+	<T>(actual: T, message?: string): actual is Falsy<T>;
 
 	/** Skip this assertion. */
 	skip(actual: any, message?: string): void;
@@ -202,7 +226,7 @@ export type IsAssertion = {
 	/**
 	 * Assert that `actual` is [the same
 	 * value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) as `expected`,
-	 * returning a boolean indicating whether the assertion passed.
+	 * returning `true` if the assertion passed and throwing otherwise.
 	 */
 	<Actual, Expected extends Actual>(actual: Actual, expected: Expected, message?: string): actual is Expected;
 
@@ -214,9 +238,9 @@ export type NotAssertion = {
 	/**
 	 * Assert that `actual` is not [the same
 	 * value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) as `expected`,
-	 * returning a boolean indicating whether the assertion passed.
+	 * returning `true` if the assertion passed and throwing otherwise.
 	 */
-	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): boolean;
+	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): true;
 
 	/** Skip this assertion. */
 	skip(actual: any, expected: any, message?: string): void;
@@ -225,9 +249,9 @@ export type NotAssertion = {
 export type NotDeepEqualAssertion = {
 	/**
 	 * Assert that `actual` is not [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
-	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 * `expected`, returning `true` if the assertion passed and throwing otherwise.
 	 */
-	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): boolean;
+	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): true;
 
 	/** Skip this assertion. */
 	skip(actual: any, expected: any, message?: string): void;
@@ -235,29 +259,40 @@ export type NotDeepEqualAssertion = {
 
 export type NotRegexAssertion = {
 	/**
-	 * Assert that `string` does not match the regular expression, returning a boolean indicating whether the assertion
-	 * passed.
+	 * Assert that `string` does not match the regular expression, returning `true` if the assertion passed and throwing
+	 * otherwise.
 	 */
-	(string: string, regex: RegExp, message?: string): boolean;
+	(string: string, regex: RegExp, message?: string): true;
 
 	/** Skip this assertion. */
 	skip(string: string, regex: RegExp, message?: string): void;
 };
 
 export type NotThrowsAssertion = {
-	/** Assert that the function does not throw. */
-	(fn: () => any, message?: string): void;
+	/**
+	 * Assert that the function does not throw, returning `true` if the assertion passed and throwing otherwise.
+	 */
+	(fn: () => any, message?: string): true;
 
 	/** Skip this assertion. */
 	skip(fn: () => any, message?: string): void;
 };
 
 export type NotThrowsAsyncAssertion = {
-	/** Assert that the async function does not throw. You must await the result. */
-	(fn: () => PromiseLike<any>, message?: string): Promise<void>;
+	/**
+	 * Assert that the async function does not throw, returning a promise for `true` if the assertion passesd and a
+	 * rejected promise otherwise.
+	 *
+	 * You must await the result.
+	 */
+	(fn: () => PromiseLike<any>, message?: string): Promise<true>;
 
-	/** Assert that the promise does not reject. You must await the result. */
-	(promise: PromiseLike<any>, message?: string): Promise<void>;
+	/** Assert that the promise does not reject, returning a promise for `true` if the assertion passesd and a
+	 * rejected promise otherwise.
+	 *
+	 * You must await the result.
+	 */
+	(promise: PromiseLike<any>, message?: string): Promise<true>;
 
 	/** Skip this assertion. */
 	skip(nonThrower: any, message?: string): void;
@@ -265,7 +300,7 @@ export type NotThrowsAsyncAssertion = {
 
 export type PassAssertion = {
 	/** Count a passing assertion, always returning `true`. */
-	(message?: string): boolean;
+	(message?: string): true;
 
 	/** Skip this assertion. */
 	skip(message?: string): void;
@@ -273,9 +308,10 @@ export type PassAssertion = {
 
 export type RegexAssertion = {
 	/**
-	 * Assert that `string` matches the regular expression, returning a boolean indicating whether the assertion passed.
+	 * Assert that `string` matches the regular expression, returning `true` if the assertion passed and throwing
+	 * otherwise.
 	 */
-	(string: string, regex: RegExp, message?: string): boolean;
+	(string: string, regex: RegExp, message?: string): true;
 
 	/** Skip this assertion. */
 	skip(string: string, regex: RegExp, message?: string): void;
@@ -286,8 +322,10 @@ export type SnapshotAssertion = {
 	 * Assert that `expected` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to a
 	 * previously recorded [snapshot](https://github.com/concordancejs/concordance#serialization-details), or if
 	 * necessary record a new snapshot.
+	 *
+	 * Returns `true` if the assertion passed and throws otherwise.
 	 */
-	(expected: any, message?: string): void;
+	(expected: any, message?: string): true;
 
 	/** Skip this assertion. */
 	skip(expected: any, message?: string): void;
@@ -295,10 +333,16 @@ export type SnapshotAssertion = {
 
 export type ThrowsAssertion = {
 	/**
-	 * Assert that the function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error value.
-	 * The error must satisfy all expectations. Returns undefined when the assertion fails.
+	 * Assert that the function throws a native error. The error must satisfy all expectations. Returns the error value if
+	 * the assertion passes and throws otherwise.
 	 */
-	<ErrorType extends ErrorConstructor | Error>(fn: () => any, expectations?: ThrowsExpectation<ErrorType>, message?: string): ThrownError<ErrorType> | undefined;
+	<ErrorType extends ErrorConstructor | Error>(fn: () => any, expectations?: ThrowsExpectation<ErrorType>, message?: string): ThrownError<ErrorType>;
+
+	/**
+	 * Assert that the function throws. The error must satisfy all expectations. Returns the error value if the assertion
+	 * passes and throws otherwise.
+	 */
+	(fn: () => any, expectations?: ThrowsAnyExpectation, message?: string): unknown;
 
 	/** Skip this assertion. */
 	skip(fn: () => any, expectations?: any, message?: string): void;
@@ -306,17 +350,28 @@ export type ThrowsAssertion = {
 
 export type ThrowsAsyncAssertion = {
 	/**
-	 * Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
-	 * value. Returns undefined when the assertion fails. You must await the result. The error must satisfy all expectations.
+	 * Assert that the async function throws a native error. You must await the result. The error must satisfy all
+	 * expectations. Returns a promise for the error value if the assertion passes and a rejected promise otherwise.
+	 */
+	<ErrorType extends ErrorConstructor | Error>(fn: () => PromiseLike<any>, expectations?: ThrowsExpectation<ErrorType>, message?: string): Promise<ThrownError<ErrorType>>;
+
+	/**
+	 * Assert that the promise rejects with a native error. You must await the result. The error must satisfy all
+	 * expectations. Returns a promise for the error value if the assertion passes and a rejected promise otherwise.
 	 */
-	<ErrorType extends ErrorConstructor | Error>(fn: () => PromiseLike<any>, expectations?: ThrowsExpectation<ErrorType>, message?: string): Promise<ThrownError<ErrorType> | undefined>;
+	<ErrorType extends ErrorConstructor | Error>(promise: PromiseLike<any>, expectations?: ThrowsExpectation<ErrorType>, message?: string): Promise<ThrownError<ErrorType>>;
 
 	/**
-	 * Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
-	 * rejection reason. Returns undefined when the assertion fails. You must await the result. The error must satisfy all
-	 * expectations.
+	 * Assert that the async function throws. You must await the result. The error must satisfy all expectations. Returns
+	 * a promise for the error value if the assertion passes and a rejected promise otherwise.
 	 */
-	<ErrorType extends ErrorConstructor | Error>(promise: PromiseLike<any>, expectations?: ThrowsExpectation<ErrorType>, message?: string): Promise<ThrownError<ErrorType> | undefined>;
+	(fn: () => PromiseLike<any>, expectations?: ThrowsAnyExpectation, message?: string): Promise<unknown>;
+
+	/**
+	 * Assert that the promise rejects. You must await the result. The error must satisfy all expectations. Returns a
+	 * promise for the error value if the assertion passes and a rejected promise otherwise.
+	 */
+	(promise: PromiseLike<any>, expectations?: ThrowsAnyExpectation, message?: string): Promise<unknown>;
 
 	/** Skip this assertion. */
 	skip(thrower: any, expectations?: any, message?: string): void;
@@ -324,7 +379,7 @@ export type ThrowsAsyncAssertion = {
 
 export type TrueAssertion = {
 	/**
-	 * Assert that `actual` is strictly true, returning a boolean indicating whether the assertion passed.
+	 * Assert that `actual` is strictly true, returning `true` if the assertion passed and throwing otherwise.
 	 */
 	(actual: any, message?: string): actual is true;
 
@@ -334,10 +389,13 @@ export type TrueAssertion = {
 
 export type TruthyAssertion = {
 	/**
-	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
-	 * indicating whether the assertion passed.
+	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning `true` if the
+	 * assertion passed and throwing otherwise.
+	 *
+	 * Note: An `else` clause using this as a type guard will be subtly incorrect for `string` and `number` types and will
+	 * not give `0` or `''` as a potential value in an `else` clause.
 	 */
-	(actual: any, message?: string): boolean;
+	<T>(actual: T, message?: string): actual is T extends Falsy<T> ? never : T;
 
 	/** Skip this assertion. */
 	skip(actual: any, message?: string): void;

package/types/shared-worker.d.cts

@@ -1,5 +1,3 @@
-import type {URL} from 'node:url';
-
 export namespace SharedWorker {
 	export type ProtocolIdentifier = 'ava-4';
 

package/types/state-change-events.d.cts

@@ -0,0 +1,143 @@
+type ErrorSource = {
+	isDependency: boolean;
+	isWithinProject: boolean;
+	file: string;
+	line: number;
+};
+
+type SerializedErrorBase = {
+	message: string;
+	name: string;
+	originalError: unknown;
+	stack: string;
+};
+
+type AggregateSerializedError = SerializedErrorBase & {
+	type: 'aggregate';
+	errors: SerializedError[];
+};
+
+type NativeSerializedError = SerializedErrorBase & {
+	type: 'native';
+	source: ErrorSource | undefined;
+};
+
+type AvaSerializedError = SerializedErrorBase & {
+	type: 'ava';
+	assertion: string;
+	improperUsage: unknown | undefined;
+	formattedCause: unknown | undefined;
+	formattedDetails: unknown | unknown[];
+	source: ErrorSource | undefined;
+};
+
+type SerializedError = AggregateSerializedError | NativeSerializedError | AvaSerializedError;
+
+export type StateChangeEvent = {
+	type: 'starting';
+	testFile: string;
+} | {
+	type: 'stats';
+	stats: {
+		byFile: Map<string, {
+			declaredTests: number;
+			failedHooks: number;
+			failedTests: number;
+			internalErrors: number;
+			remainingTests: number;
+			passedKnownFailingTests: number;
+			passedTests: number;
+			selectedTests: number;
+			selectingLines: boolean;
+			skippedTests: number;
+			todoTests: number;
+			uncaughtExceptions: number;
+			unhandledRejections: number;
+		}>;
+		declaredTests: number;
+		failedHooks: number;
+		failedTests: number;
+		failedWorkers: number;
+		files: number;
+		parallelRuns: {
+			currentIndex: number;
+			totalRuns: number;
+		} | undefined;
+		finishedWorkers: number;
+		internalErrors: number;
+		remainingTests: number;
+		passedKnownFailingTests: number;
+		passedTests: number;
+		selectedTests: number;
+		sharedWorkerErrors: number;
+		skippedTests: number;
+		timedOutTests: number;
+		timeouts: number;
+		todoTests: number;
+		uncaughtExceptions: number;
+		unhandledRejections: number;
+	};
+} | {
+	type: 'declared-test';
+	title: string;
+	knownFailing: boolean;
+	todo: boolean;
+	testFile: string;
+} | {
+	type: 'selected-test';
+	title: string;
+	knownFailing: boolean;
+	skip: boolean;
+	todo: boolean;
+	testFile: string;
+} | {
+	type: 'test-register-log-reference';
+	title: string;
+	logs: string[];
+	testFile: string;
+} | {
+	type: 'test-passed';
+	title: string;
+	duration: number;
+	knownFailing: boolean;
+	logs: string[];
+	testFile: string;
+} | {
+	type: 'test-failed';
+	title: string;
+	err: SerializedError;
+	duration: number;
+	knownFailing: boolean;
+	logs: string[];
+	testFile: string;
+} | {
+	type: 'worker-finished';
+	forcedExit: boolean;
+	testFile: string;
+} | {
+	type: 'worker-failed';
+	nonZeroExitCode?: boolean;
+	signal?: string;
+	err?: SerializedError;
+} | {
+	type: 'touched-files';
+	files: {
+		changedFiles: string[];
+		temporaryFiles: string[];
+	};
+} | {
+	type: 'worker-stdout';
+	chunk: Uint8Array;
+	testFile: string;
+} | {
+	type: 'worker-stderr';
+	chunk: Uint8Array;
+	testFile: string;
+} | {
+	type: 'timeout';
+	period: number;
+	pendingTests: Map<string, Set<string>>;
+}
+| {
+	type: 'end';
+};

package/types/test-fn.d.cts

@@ -39,11 +39,16 @@ export type PlanFn = {
 	skip(count: number): void;
 };
 
-/**
- * Set a timeout for the test, in milliseconds. The test will fail if the timeout is exceeded.
- * The timeout is reset each time an assertion is made.
- */
-export type TimeoutFn = (ms: number, message?: string) => void;
+export type TimeoutFn = {
+	/**
+	 * Set a timeout for the test, in milliseconds. The test will fail if the timeout is exceeded.
+	 * The timeout is reset each time an assertion is made.
+	 */
+	(ms: number, message?: string): void;
+
+	/** Clear the timeout and restore the default behavior. */
+	clear(): void;
+};
 
 /** Declare a function to be run after the test has ended. */
 export type TeardownFn = (fn: (() => Promise<void>) | (() => void)) => void;

package/lib/worker/dependency-tracker.js

@@ -1,48 +0,0 @@
-import process from 'node:process';
-
-import channel from './channel.cjs';
-
-const seenDependencies = new Set();
-let newDependencies = [];
-
-function flush() {
-	if (newDependencies.length === 0) {
-		return;
-	}
-
-	channel.send({type: 'dependencies', dependencies: newDependencies});
-	newDependencies = [];
-}
-
-function track(filename) {
-	if (seenDependencies.has(filename)) {
-		return;
-	}
-
-	if (newDependencies.length === 0) {
-		process.nextTick(flush);
-	}
-
-	seenDependencies.add(filename);
-	newDependencies.push(filename);
-}
-
-const tracker = {
-	flush,
-	track,
-	install(extensions, testPath) {
-		for (const ext of Object.keys(extensions)) {
-			const wrappedHandler = extensions[ext];
-
-			extensions[ext] = (module, filename) => {
-				if (filename !== testPath) {
-					track(filename);
-				}
-
-				wrappedHandler(module, filename);
-			};
-		}
-	},
-};
-
-export default tracker;