ava 4.0.0-alpha.1 → 4.0.1

package/types/assertions.d.ts

@@ -0,0 +1,327 @@
+export type ErrorConstructor = new (...args: any[]) => Error;
+
+/** Specify one or more expectations the thrown error must satisfy. */
+export type ThrowsExpectation = {
+	/** The thrown error must have a code that equals the given string or number. */
+	code?: string | number;
+
+	/** The thrown error must be an instance of this constructor. */
+	instanceOf?: ErrorConstructor;
+
+	/** The thrown error must be strictly equal to this value. */
+	is?: Error;
+
+	/** The thrown error must have a message that equals the given string, or matches the regular expression. */
+	message?: string | RegExp;
+
+	/** The thrown error must have a name that equals the given string. */
+	name?: string;
+};
+
+export interface Assertions {
+	/**
+	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
+	 * indicating whether the assertion passed.
+	 */
+	assert: AssertAssertion;
+
+	/**
+	 * Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
+	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 */
+	deepEqual: DeepEqualAssertion;
+
+	/**
+	 * Assert that `value` is like `selector`, returning a boolean indicating whether the assertion passed.
+	 */
+	like: LikeAssertion;
+
+	/** Fail the test, always returning `false`. */
+	fail: FailAssertion;
+
+	/**
+	 * Assert that `actual` is strictly false, returning a boolean indicating whether the assertion passed.
+	 */
+	false: FalseAssertion;
+
+	/**
+	 * Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), returning a boolean
+	 * indicating whether the assertion passed.
+	 */
+	falsy: FalsyAssertion;
+
+	/**
+	 * 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.
+	 */
+	is: IsAssertion;
+
+	/**
+	 * 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.
+	 */
+	not: NotAssertion;
+
+	/**
+	 * Assert that `actual` is not [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
+	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 */
+	notDeepEqual: NotDeepEqualAssertion;
+
+	/**
+	 * Assert that `string` does not match the regular expression, returning a boolean indicating whether the assertion
+	 * passed.
+	 */
+	notRegex: NotRegexAssertion;
+
+	/** Assert that the function does not throw. */
+	notThrows: NotThrowsAssertion;
+
+	/** Assert that the async function does not throw, or that the promise does not reject. Must be awaited. */
+	notThrowsAsync: NotThrowsAsyncAssertion;
+
+	/** Count a passing assertion, always returning `true`. */
+	pass: PassAssertion;
+
+	/**
+	 * Assert that `string` matches the regular expression, returning a boolean indicating whether the assertion passed.
+	 */
+	regex: RegexAssertion;
+
+	/**
+	 * 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.
+	 */
+	snapshot: SnapshotAssertion;
+
+	/**
+	 * Assert that the function throws [an error](https://www.npmjs.com/package/is-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
+	 * with one. If so, returns a promise for the error value, which must be awaited.
+	 */
+	throwsAsync: ThrowsAsyncAssertion;
+
+	/**
+	 * Assert that `actual` is strictly true, returning a boolean indicating whether the assertion passed.
+	 */
+	true: TrueAssertion;
+
+	/**
+	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
+	 * indicating whether the assertion passed.
+	 */
+	truthy: TruthyAssertion;
+}
+
+export interface AssertAssertion {
+	/**
+	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
+	 * indicating whether the assertion passed.
+	 */
+	(actual: any, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(actual: any, message?: string): void;
+}
+
+export interface DeepEqualAssertion {
+	/**
+	 * Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to
+	 * `expected`, returning a boolean indicating whether the assertion passed.
+	 */
+	<Actual, Expected extends Actual>(actual: Actual, expected: Expected, message?: string): actual is Expected;
+
+	/** Skip this assertion. */
+	skip(actual: any, expected: any, message?: string): void;
+}
+
+export interface LikeAssertion {
+	/**
+	 * Assert that `value` is like `selector`, returning a boolean indicating whether the assertion passed.
+	 */
+	<Expected extends Record<string, any>>(value: any, selector: Expected, message?: string): value is Expected;
+
+	/** Skip this assertion. */
+	skip(value: any, selector: any, message?: string): void;
+}
+
+export interface FailAssertion {
+	/** Fail the test, always returning `false`. */
+	(message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(message?: string): void;
+}
+
+export interface FalseAssertion {
+	/**
+	 * Assert that `actual` is strictly false, returning a boolean indicating whether the assertion passed.
+	 */
+	(actual: any, message?: string): actual is false;
+
+	/** Skip this assertion. */
+	skip(actual: any, message?: string): void;
+}
+
+export interface FalsyAssertion {
+	/**
+	 * Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), returning a boolean
+	 * indicating whether the assertion passed.
+	 */
+	(actual: any, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(actual: any, message?: string): void;
+}
+
+export interface 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.
+	 */
+	<Actual, Expected extends Actual>(actual: Actual, expected: Expected, message?: string): actual is Expected;
+
+	/** Skip this assertion. */
+	skip(actual: any, expected: any, message?: string): void;
+}
+
+export interface 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.
+	 */
+	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(actual: any, expected: any, message?: string): void;
+}
+
+export interface 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.
+	 */
+	<Actual, Expected>(actual: Actual, expected: Expected, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(actual: any, expected: any, message?: string): void;
+}
+
+export interface NotRegexAssertion {
+	/**
+	 * Assert that `string` does not match the regular expression, returning a boolean indicating whether the assertion
+	 * passed.
+	 */
+	(string: string, regex: RegExp, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(string: string, regex: RegExp, message?: string): void;
+}
+
+export interface NotThrowsAssertion {
+	/** Assert that the function does not throw. */
+	(fn: () => any, message?: string): void;
+
+	/** Skip this assertion. */
+	skip(fn: () => any, message?: string): void;
+}
+
+export interface NotThrowsAsyncAssertion {
+	/** Assert that the async function does not throw. You must await the result. */
+	(fn: () => PromiseLike<any>, message?: string): Promise<void>;
+
+	/** Assert that the promise does not reject. You must await the result. */
+	(promise: PromiseLike<any>, message?: string): Promise<void>; // eslint-disable-line @typescript-eslint/unified-signatures
+
+	/** Skip this assertion. */
+	skip(nonThrower: any, message?: string): void;
+}
+
+export interface PassAssertion {
+	/** Count a passing assertion, always returning `true`. */
+	(message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(message?: string): void;
+}
+
+export interface RegexAssertion {
+	/**
+	 * Assert that `string` matches the regular expression, returning a boolean indicating whether the assertion passed.
+	 */
+	(string: string, regex: RegExp, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(string: string, regex: RegExp, message?: string): void;
+}
+
+export interface 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.
+	 */
+	(expected: any, message?: string): void;
+
+	/** Skip this assertion. */
+	skip(expected: any, message?: string): void;
+}
+
+export interface 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.
+	 */
+	<ThrownError extends Error>(fn: () => any, expectations?: ThrowsExpectation, message?: string): ThrownError | undefined;
+
+	/** Skip this assertion. */
+	skip(fn: () => any, expectations?: any, message?: string): void;
+}
+
+export interface 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.
+	 */
+	<ThrownError extends Error>(fn: () => PromiseLike<any>, expectations?: ThrowsExpectation, message?: string): Promise<ThrownError | undefined>;
+
+	/**
+	 * 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.
+	 */
+	<ThrownError extends Error>(promise: PromiseLike<any>, expectations?: ThrowsExpectation, message?: string): Promise<ThrownError | undefined>; // eslint-disable-line @typescript-eslint/unified-signatures
+
+	/** Skip this assertion. */
+	skip(thrower: any, expectations?: any, message?: string): void;
+}
+
+export interface TrueAssertion {
+	/**
+	 * Assert that `actual` is strictly true, returning a boolean indicating whether the assertion passed.
+	 */
+	(actual: any, message?: string): actual is true;
+
+	/** Skip this assertion. */
+	skip(actual: any, message?: string): void;
+}
+
+export interface TruthyAssertion {
+	/**
+	 * Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), returning a boolean
+	 * indicating whether the assertion passed.
+	 */
+	(actual: any, message?: string): boolean;
+
+	/** Skip this assertion. */
+	skip(actual: any, message?: string): void;
+}

package/types/subscribable.ts

@@ -0,0 +1,6 @@
+export interface Subscribable {
+	subscribe(observer: {
+		error(error: any): void;
+		complete(): void;
+	}): void;
+}

package/types/test-fn.d.ts

@@ -0,0 +1,231 @@
+import type {Assertions} from './assertions';
+import type {Subscribable} from './subscribable';
+import type {TryFn} from './try-fn';
+
+/** The `t` value passed to test & hook implementations. */
+export interface ExecutionContext<Context = unknown> extends Assertions {
+	/** Test context, shared with hooks. */
+	context: Context;
+
+	/** Title of the test or hook. */
+	readonly title: string;
+
+	/** Whether the test has passed. Only accurate in afterEach hooks. */
+	readonly passed: boolean;
+
+	readonly log: LogFn;
+	readonly plan: PlanFn;
+	readonly teardown: TeardownFn;
+	readonly timeout: TimeoutFn;
+	readonly try: TryFn<Context>;
+}
+
+export interface LogFn {
+	/** Log one or more values. */
+	(...values: any[]): void;
+
+	/** Skip logging. */
+	skip(...values: any[]): void;
+}
+
+export interface PlanFn {
+	/**
+	 * Plan how many assertion there are in the test. The test will fail if the actual assertion count doesn't match the
+	 * number of planned assertions. See [assertion planning](https://github.com/avajs/ava#assertion-planning).
+	 */
+	(count: number): void;
+
+	/** Don't plan assertions. */
+	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;
+
+/** Declare a function to be run after the test has ended. */
+export type TeardownFn = (fn: () => void) => void;
+
+export type ImplementationFn<Args extends unknown[], Context = unknown> =
+	((t: ExecutionContext<Context>, ...args: Args) => PromiseLike<void>) |
+	((t: ExecutionContext<Context>, ...args: Args) => Subscribable) |
+	((t: ExecutionContext<Context>, ...args: Args) => void);
+
+export type TitleFn<Args extends unknown[]> = (providedTitle: string | undefined, ...args: Args) => string;
+
+/** A reusable test or hook implementation. */
+export type Macro<Args extends unknown[], Context = unknown> = {
+	/** The function that is executed when the macro is used. */
+	readonly exec: ImplementationFn<Args, Context>;
+
+	/** Generates a test title when this macro is used. */
+	readonly title?: TitleFn<Args>;
+};
+
+/** A test or hook implementation. */
+export type Implementation<Args extends unknown[], Context = unknown> = ImplementationFn<Args, Context> | Macro<Args, Context>;
+
+export interface TestFn<Context = unknown> {
+	/** Declare a concurrent test. Additional arguments are passed to the implementation or macro. */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a concurrent test that uses a macro. Additional arguments are passed to the macro.
+	 * The macro is responsible for generating a unique test title.
+	 */
+	<Args extends unknown[]>(macro: Macro<Args, Context>, ...args: Args): void;
+
+	after: AfterFn<Context>;
+	afterEach: AfterFn<Context>;
+	before: BeforeFn<Context>;
+	beforeEach: BeforeFn<Context>;
+	failing: FailingFn<Context>;
+	macro: MacroFn<Context>;
+	meta: Meta;
+	only: OnlyFn<Context>;
+	serial: SerialFn<Context>;
+	skip: SkipFn<Context>;
+	todo: TodoFn;
+}
+
+export interface AfterFn<Context = unknown> {
+	/**
+	 * Declare a hook that is run once, after all tests have passed.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a hook that is run once, after all tests have passed.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	always: AlwaysInterface<Context>;
+	skip: HookSkipFn<Context>;
+}
+
+export interface AlwaysInterface<Context = unknown> {
+	/**
+	 * Declare a hook that is run once, after all tests are done.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a hook that is run once, after all tests are done.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	skip: HookSkipFn<Context>;
+}
+
+export interface BeforeFn<Context = unknown> {
+	/**
+	 * Declare a hook that is run once, before all tests.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a hook that is run once, before all tests.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	skip: HookSkipFn<Context>;
+}
+
+export interface FailingFn<Context = unknown> {
+	/**
+	 * Declare a concurrent test that is expected to fail.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a concurrent test, using a macro, that is expected to fail.
+	 * Additional arguments are passed to the macro. The macro is responsible for generating a unique test title.
+	 */
+	<Args extends unknown[]>(macro: Macro<Args, Context>, ...args: Args): void;
+
+	only: OnlyFn<Context>;
+	skip: SkipFn<Context>;
+}
+
+export interface HookSkipFn<Context = unknown> {
+	/** Skip this hook. */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/** Skip this hook. */
+	<Args extends unknown[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
+}
+
+export interface OnlyFn<Context = unknown> {
+	/**
+	 * Declare a test. Only this test and others declared with `.only()` are run.
+	 * Additional arguments are passed to the implementation or macro.
+	 */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a test that uses a macro. Only this test and others declared with `.only()` are run.
+	 * Additional arguments are passed to the macro. The macro is responsible for generating a unique test title.
+	 */
+	<Args extends unknown[]>(macro: Macro<Args, Context>, ...args: Args): void;
+}
+
+export interface SerialFn<Context = unknown> {
+	/** Declare a serial test. Additional arguments are passed to the implementation or macro. */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/**
+	 * Declare a serial test that uses a macro. The macro is responsible for generating a unique test title.
+	 */
+	<Args extends unknown[]>(macro: Macro<Args, Context>, ...args: Args): void;
+
+	after: AfterFn<Context>;
+	afterEach: AfterFn<Context>;
+	before: BeforeFn<Context>;
+	beforeEach: BeforeFn<Context>;
+	failing: FailingFn<Context>;
+	only: OnlyFn<Context>;
+	skip: SkipFn<Context>;
+	todo: TodoFn;
+}
+
+export interface SkipFn<Context = unknown> {
+	/** Skip this test. */
+	<Args extends unknown[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
+
+	/** Skip this test. */
+	<Args extends unknown[]>(macro: Macro<Args, Context>, ...args: Args): void;
+}
+
+/** Declare a test that should be implemented later. */
+export type TodoFn = (title: string) => void;
+
+export type MacroDeclarationOptions<Args extends unknown[], Context = unknown> = {
+	/** The function that is executed when the macro is used. */
+	exec: ImplementationFn<Args, Context>;
+
+	/** The function responsible for generating a unique title when the macro is used. */
+	title: TitleFn<Args>;
+};
+
+export interface MacroFn<Context = unknown> {
+	/** Declare a reusable test implementation. */
+	<Args extends unknown[]>(/** The function that is executed when the macro is used. */ exec: ImplementationFn<Args, Context>): Macro<Args, Context>;
+	<Args extends unknown[]>(declaration: MacroDeclarationOptions<Args, Context>): Macro<Args, Context>; // eslint-disable-line @typescript-eslint/unified-signatures
+}
+
+export interface Meta {
+	/** Path to the test file being executed. */
+	file: string;
+
+	/** Directory where snapshots are stored. */
+	snapshotDirectory: string;
+}

package/types/try-fn.d.ts

@@ -0,0 +1,58 @@
+import type {Implementation} from './test-fn';
+
+export type CommitDiscardOptions = {
+	/**
+	 * Whether the logs should be included in those of the parent test.
+	 */
+	retainLogs?: boolean;
+};
+
+export interface AssertionError extends Error {}
+
+export interface TryResult {
+	/**
+	* Title of the attempt, helping you tell attempts aparts.
+	*/
+	title: string;
+
+	/**
+	* Indicates whether all assertions passed, or at least one failed.
+	*/
+	passed: boolean;
+
+	/**
+	* Errors raised for each failed assertion.
+	*/
+	errors: AssertionError[];
+
+	/**
+	 * Logs created during the attempt using `t.log()`. Contains formatted values.
+	 */
+	logs: string[];
+
+	/**
+	 * Commit the attempt. Counts as one assertion for the plan count. If the
+	 * attempt failed, calling this will also cause your test to fail.
+	 */
+	commit(options?: CommitDiscardOptions): void;
+
+	/**
+	 * Discard the attempt.
+	 */
+	discard(options?: CommitDiscardOptions): void;
+}
+
+export interface TryFn<Context = unknown> {
+	/**
+	 * Attempt to run some assertions. The result must be explicitly committed or discarded or else
+	 * the test will fail. The title may help distinguish attempts from one another.
+	 */
+	<Args extends unknown[]>(title: string, fn: Implementation<Args, Context>, ...args: Args): Promise<TryResult>;
+
+	/**
+	 * Attempt to run some assertions. The result must be explicitly committed or discarded or else
+	 * the test will fail.
+	 */
+	<Args extends unknown[]>(fn: Implementation<Args, Context>, ...args: Args): Promise<TryResult>;
+}
+

package/cli.js

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-const debug = require('debug')('ava');
-const importLocal = require('import-local');
-
-// Prefer the local installation of AVA
-if (importLocal(__filename)) {
-	debug('Using local install of AVA');
-} else {
-	require('./lib/cli').run();
-}

package/index.js

@@ -1,8 +0,0 @@
-'use strict';
-
-// Ensure the same AVA install is loaded by the test file as by the test worker
-if (process.env.AVA_PATH && process.env.AVA_PATH !== __dirname) {
-	module.exports = require(process.env.AVA_PATH);
-} else {
-	module.exports = require('./lib/worker/main');
-}