///
export interface ObservableLike {
subscribe(observer: (value: unknown) => void): void;
[Symbol.observable](): ObservableLike;
}
export type Constructor = (new (...args: Array) => any);
/** 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?: Constructor;
/** 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;
};
/** Options that can be passed to the `t.snapshot()` assertion. */
export type SnapshotOptions = {
/** If provided and not an empty string, used to select the snapshot to compare the `expected` value against. */
id?: string;
};
export interface Assertions {
/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). Comes with power-assert. */
assert: AssertAssertion;
/** Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
deepEqual: DeepEqualAssertion;
/** Fail the test. */
fail: FailAssertion;
/** Assert that `actual` is strictly false. */
false: FalseAssertion;
/** Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy). */
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`.
*/
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`.
*/
not: NotAssertion;
/** Assert that `actual` is not [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
notDeepEqual: NotDeepEqualAssertion;
/** Assert that `string` does not match the regular expression. */
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. */
pass: PassAssertion;
/** Assert that `string` matches the regular expression. */
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. */
true: TrueAssertion;
/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). */
truthy: TruthyAssertion;
}
export interface AssertAssertion {
/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). Comes with power-assert. */
(actual: any, message?: string): void;
/** 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`. */
(actual: ValueType, expected: ValueType, message?: string): void;
/** Skip this assertion. */
skip(actual: any, expected: any, message?: string): void;
}
export interface FailAssertion {
/** Fail the test. */
(message?: string): void;
/** Skip this assertion. */
skip(message?: string): void;
}
export interface FalseAssertion {
/** Assert that `actual` is strictly false. */
(actual: any, message?: string): void;
/** 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). */
(actual: any, message?: string): void;
/** 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`.
*/
(actual: ValueType, expected: ValueType, message?: string): void;
/** 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`.
*/
(actual: ValueType, expected: ValueType, message?: string): void;
/** 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`. */
(actual: ValueType, expected: ValueType, message?: string): void;
/** Skip this assertion. */
skip(actual: any, expected: any, message?: string): void;
}
export interface NotRegexAssertion {
/** Assert that `string` does not match the regular expression. */
(string: string, regex: RegExp, message?: string): void;
/** 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, message?: string): Promise;
/** Assert that the promise does not reject. You must await the result. */
(promise: PromiseLike, message?: string): Promise;
/** Skip this assertion. */
skip(nonThrower: any, message?: string): void;
}
export interface PassAssertion {
/** Count a passing assertion. */
(message?: string): void;
/** Skip this assertion. */
skip(message?: string): void;
}
export interface RegexAssertion {
/** Assert that `string` matches the regular expression. */
(string: string, regex: RegExp, message?: string): void;
/** 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;
/**
* 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) (selected
* through `options.id` if provided), or if necessary record a new snapshot.
*/
(expected: any, options: SnapshotOptions, message?: string): void;
/** Skip this assertion. */
skip(expected: any, message?: string): void;
/** Skip this assertion. */
skip(expected: any, options: SnapshotOptions, 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.
*/
(fn: () => any, expectations?: null, message?: string): ThrownError;
/**
* Assert that the function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error value.
* The error must be an instance of the given constructor.
*/
(fn: () => any, constructor: Constructor, message?: string): ThrownError;
/**
* Assert that the function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error value.
* The error must have a message that matches the regular expression.
*/
(fn: () => any, regex: RegExp, message?: string): ThrownError;
/**
* Assert that the function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error value.
* The error must have a message equal to `errorMessage`.
*/
(fn: () => any, errorMessage: string, message?: string): ThrownError;
/**
* 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.
*/
(fn: () => any, expectations: ThrowsExpectation, message?: string): ThrownError;
/** 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. You must await the result.
*/
(fn: () => PromiseLike, expectations?: null, message?: string): Promise;
/**
* Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
* value. You must await the result. The error must be an instance of the given constructor.
*/
(fn: () => PromiseLike, constructor: Constructor, message?: string): Promise;
/**
* Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
* value. You must await the result. The error must have a message that matches the regular expression.
*/
(fn: () => PromiseLike, regex: RegExp, message?: string): Promise;
/**
* Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
* value. You must await the result. The error must have a message equal to `errorMessage`.
*/
(fn: () => PromiseLike, errorMessage: string, message?: string): Promise;
/**
* Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
* value. You must await the result. The error must satisfy all expectations.
*/
(fn: () => PromiseLike, expectations: ThrowsExpectation, message?: string): Promise;
/**
* Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
* rejection reason. You must await the result.
*/
(promise: PromiseLike, expectations?: null, message?: string): Promise;
/**
* Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
* rejection reason. You must await the result. The error must be an instance of the given constructor.
*/
(promise: PromiseLike, constructor: Constructor, message?: string): Promise;
/**
* Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
* rejection reason. You must await the result. The error must have a message that matches the regular expression.
*/
(promise: PromiseLike, regex: RegExp, message?: string): Promise;
/**
* Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
* rejection reason. You must await the result. The error must have a message equal to `errorMessage`.
*/
(promise: PromiseLike, errorMessage: string, message?: string): Promise;
/**
* Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
* rejection reason. You must await the result. The error must satisfy all expectations.
*/
(promise: PromiseLike, expectations: ThrowsExpectation, message?: string): Promise;
/** Skip this assertion. */
skip(thrower: any, expectations?: any, message?: string): void;
}
export interface TrueAssertion {
/** Assert that `actual` is strictly true. */
(actual: any, message?: string): void;
/** 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). */
(actual: any, message?: string): void;
/** Skip this assertion. */
skip(actual: any, message?: string): void;
}
/** The `t` value passed to test & hook implementations. */
export interface ExecutionContext extends Assertions {
/** Test context, shared with hooks. */
context: Context;
/** Title of the test or hook. */
readonly title: string;
log: LogFn;
plan: PlanFn;
timeout: TimeoutFn;
}
export interface LogFn {
/** Log one or more values. */
(...values: Array): void;
/** Skip logging. */
skip(...values: Array): 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;
}
export interface 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): void;
}
/** The `t` value passed to implementations for tests & hooks declared with the `.cb` modifier. */
export interface CbExecutionContext extends ExecutionContext {
/**
* End the test. If `error` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) the test or hook
* will fail.
*/
end(error?: any): void;
}
export type ImplementationResult = PromiseLike | ObservableLike | void;
export type Implementation = (t: ExecutionContext) => ImplementationResult;
export type CbImplementation = (t: CbExecutionContext) => ImplementationResult;
/** A reusable test or hook implementation. */
export type UntitledMacro = (t: ExecutionContext, ...args: Args) => ImplementationResult;
/** A reusable test or hook implementation. */
export type Macro = UntitledMacro & {
/**
* Implement this function to generate a test (or hook) title whenever this macro is used. `providedTitle` contains
* the title provided when the test or hook was declared. Also receives the remaining test arguments.
*/
title?: (providedTitle: string | undefined, ...args: Args) => string;
}
export type EitherMacro = Macro | UntitledMacro;
/** Alias for a single macro, or an array of macros. */
export type OneOrMoreMacros = EitherMacro | [EitherMacro, ...EitherMacro[]];
/** A reusable test or hook implementation, for tests & hooks declared with the `.cb` modifier. */
export type UntitledCbMacro = (t: CbExecutionContext, ...args: Args) => ImplementationResult
/** A reusable test or hook implementation, for tests & hooks declared with the `.cb` modifier. */
export type CbMacro = UntitledCbMacro & {
title?: (providedTitle: string | undefined, ...args: Args) => string;
}
export type EitherCbMacro = CbMacro | UntitledCbMacro;
/** Alias for a single macro, or an array of macros, used for tests & hooks declared with the `.cb` modifier. */
export type OneOrMoreCbMacros = EitherCbMacro | [EitherCbMacro, ...EitherCbMacro[]];
export interface TestInterface {
/** Declare a concurrent test. */
(title: string, implementation: Implementation): void;
/** Declare a concurrent test that uses one or more macros. Additional arguments are passed to the macro. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void
/** Declare a concurrent test that uses one or more macros. The macro is responsible for generating a unique test title. */
(macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that is run once, after all tests have passed. */
after: AfterInterface;
/** Declare a hook that is run after each passing test. */
afterEach: AfterInterface;
/** Declare a hook that is run once, before all tests. */
before: BeforeInterface;
/** Declare a hook that is run before each test. */
beforeEach: BeforeInterface;
/** Declare a test that must call `t.end()` when it's done. */
cb: CbInterface;
/** Declare a test that is expected to fail. */
failing: FailingInterface;
/** Declare tests and hooks that are run serially. */
serial: SerialInterface;
only: OnlyInterface;
skip: SkipInterface;
todo: TodoDeclaration;
meta: MetaInterface;
}
export interface AfterInterface {
/** Declare a hook that is run once, after all tests have passed. */
(implementation: Implementation): void;
/** Declare a hook that is run once, after all tests have passed. */
(title: string, implementation: Implementation): void;
/** Declare a hook that is run once, after all tests have passed. Additional arguments are passed to the macro. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that is run once, after all tests have passed. */
(macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that is run once, after all tests are done. */
always: AlwaysInterface;
/** Declare a hook that must call `t.end()` when it's done. */
cb: HookCbInterface;
skip: HookSkipInterface;
}
export interface AlwaysInterface {
/** Declare a hook that is run once, after all tests are done. */
(implementation: Implementation): void;
/** Declare a hook that is run once, after all tests are done. */
(title: string, implementation: Implementation): void;
/** Declare a hook that is run once, after all tests are done. Additional arguments are passed to the macro. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that is run once, after all tests are done. */
(macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that must call `t.end()` when it's done. */
cb: HookCbInterface;
skip: HookSkipInterface;
}
export interface BeforeInterface {
/** Declare a hook that is run once, before all tests. */
(implementation: Implementation): void;
/** Declare a hook that is run once, before all tests. */
(title: string, implementation: Implementation): void;
/** Declare a hook that is run once, before all tests. Additional arguments are passed to the macro. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that is run once, before all tests. */
(macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a hook that must call `t.end()` when it's done. */
cb: HookCbInterface;
skip: HookSkipInterface;
}
export interface CbInterface {
/** Declare a test that must call `t.end()` when it's done. */
(title: string, implementation: CbImplementation): void;
/**
* Declare a concurrent test that uses one or more macros. The macros must call `t.end()` when they're done.
* Additional arguments are passed to the macro.
*/
(title: string, macros: OneOrMoreCbMacros, ...rest: T): void;
/**
* Declare a concurrent test that uses one or more macros. The macros must call `t.end()` when they're done.
* The macro is responsible for generating a unique test title.
*/
(macros: OneOrMoreCbMacros, ...rest: T): void;
/** Declare a test that is expected to fail. */
failing: CbFailingInterface;
only: CbOnlyInterface;
skip: CbSkipInterface;
}
export interface CbFailingInterface {
/** Declare a test that must call `t.end()` when it's done. The test is expected to fail. */
(title: string, implementation: CbImplementation): void;
/**
* Declare a test that uses one or more macros. The macros must call `t.end()` when they're done.
* Additional arguments are passed to the macro. The test is expected to fail.
*/
(title: string, macros: OneOrMoreCbMacros, ...rest: T): void;
/**
* Declare a test that uses one or more macros. The macros must call `t.end()` when they're done.
* The test is expected to fail.
*/
(macros: OneOrMoreCbMacros, ...rest: T): void;
only: CbOnlyInterface;
skip: CbSkipInterface;
}
export interface CbOnlyInterface {
/**
* Declare a test that must call `t.end()` when it's done. Only this test and others declared with `.only()` are run.
*/
(title: string, implementation: CbImplementation): void;
/**
* Declare a test that uses one or more macros. The macros must call `t.end()` when they're done.
* Additional arguments are passed to the macro. Only this test and others declared with `.only()` are run.
*/
(title: string, macros: OneOrMoreCbMacros, ...rest: T): void;
/**
* Declare a test that uses one or more macros. The macros must call `t.end()` when they're done.
* Additional arguments are passed to the macro. Only this test and others declared with `.only()` are run.
*/
(macros: OneOrMoreCbMacros, ...rest: T): void;
}
export interface CbSkipInterface {
/** Skip this test. */
(title: string, implementation: CbImplementation): void;
/** Skip this test. */
(title: string, macros: OneOrMoreCbMacros, ...rest: T): void;
/** Skip this test. */
(macros: OneOrMoreCbMacros, ...rest: T): void;
}
export interface FailingInterface {
/** Declare a concurrent test. The test is expected to fail. */
(title: string, implementation: Implementation): void;
/**
* Declare a concurrent test that uses one or more macros. Additional arguments are passed to the macro.
* The test is expected to fail.
*/
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/**
* Declare a concurrent test that uses one or more macros. The macro is responsible for generating a unique test title.
* The test is expected to fail.
*/
(macros: OneOrMoreMacros, ...rest: T): void;
only: OnlyInterface;
skip: SkipInterface;
}
export interface HookCbInterface {
/** Declare a hook that must call `t.end()` when it's done. */
(implementation: CbImplementation): void;
/** Declare a hook that must call `t.end()` when it's done. */
(title: string, implementation: CbImplementation): void;
/**
* Declare a hook that uses one or more macros. The macros must call `t.end()` when they're done.
* Additional arguments are passed to the macro.
*/
(title: string, macros: OneOrMoreCbMacros, ...rest: T): void;
/**
* Declare a hook that uses one or more macros. The macros must call `t.end()` when they're done.
*/
(macros: OneOrMoreCbMacros, ...rest: T): void;
skip: HookCbSkipInterface;
}
export interface HookCbSkipInterface {
/** Skip this hook. */
(implementation: CbImplementation): void;
/** Skip this hook. */
(title: string, implementation: CbImplementation): void;
/** Skip this hook. */
(title: string, macros: OneOrMoreCbMacros, ...rest: T): void;
/** Skip this hook. */
(macros: OneOrMoreCbMacros, ...rest: T): void;
}
export interface HookSkipInterface {
/** Skip this hook. */
(implementation: Implementation): void;
/** Skip this hook. */
(title: string, implementation: Implementation): void;
/** Skip this hook. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/** Skip this hook. */
(macros: OneOrMoreMacros, ...rest: T): void;
}
export interface OnlyInterface {
/** Declare a test. Only this test and others declared with `.only()` are run. */
(title: string, implementation: Implementation): void;
/**
* Declare a test that uses one or more macros. Additional arguments are passed to the macro.
* Only this test and others declared with `.only()` are run.
*/
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/**
* Declare a test that uses one or more macros. The macro is responsible for generating a unique test title.
* Only this test and others declared with `.only()` are run.
*/
(macros: OneOrMoreMacros, ...rest: T): void;
}
export interface SerialInterface {
/** Declare a serial test. */
(title: string, implementation: Implementation): void;
/** Declare a serial test that uses one or more macros. Additional arguments are passed to the macro. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/**
* Declare a serial test that uses one or more macros. The macro is responsible for generating a unique test title.
*/
(macros: OneOrMoreMacros, ...rest: T): void;
/** Declare a serial hook that is run once, after all tests have passed. */
after: AfterInterface;
/** Declare a serial hook that is run after each passing test. */
afterEach: AfterInterface;
/** Declare a serial hook that is run once, before all tests. */
before: BeforeInterface;
/** Declare a serial hook that is run before each test. */
beforeEach: BeforeInterface;
/** Declare a serial test that must call `t.end()` when it's done. */
cb: CbInterface;
/** Declare a serial test that is expected to fail. */
failing: FailingInterface;
only: OnlyInterface;
skip: SkipInterface;
todo: TodoDeclaration;
}
export interface SkipInterface {
/** Skip this test. */
(title: string, implementation: Implementation): void;
/** Skip this test. */
(title: string, macros: OneOrMoreMacros, ...rest: T): void;
/** Skip this test. */
(macros: OneOrMoreMacros, ...rest: T): void;
}
export interface TodoDeclaration {
/** Declare a test that should be implemented later. */
(title: string): void;
}
export interface MetaInterface {
/** Path to the test file being executed. */
file: string;
}
/** Call to declare a test, or chain to declare hooks or test modifiers */
declare const test: TestInterface;
/** Call to declare a test, or chain to declare hooks or test modifiers */
export default test;
/** Call to declare a hook that is run once, after all tests have passed, or chain to declare modifiers. */
export const after: AfterInterface;
/** Call to declare a hook that is run after each passing test, or chain to declare modifiers. */
export const afterEach: AfterInterface;
/** Call to declare a hook that is run once, before all tests, or chain to declare modifiers. */
export const before: BeforeInterface;
/** Call to declare a hook that is run before each test, or chain to declare modifiers. */
export const beforeEach: BeforeInterface;
/** Call to declare a test that must invoke `t.end()` when it's done, or chain to declare modifiers. */
export const cb: CbInterface;
/** Call to declare a test that is expected to fail, or chain to declare modifiers. */
export const failing: FailingInterface;
/** Call to declare a test that is run exclusively, along with other tests declared with `.only()`. */
export const only: OnlyInterface;
/** Call to declare a serial test, or chain to declare serial hooks or test modifiers. */
export const serial: SerialInterface;
/** Skip this test. */
export const skip: SkipInterface;
/** Declare a test that should be implemented later. */
export const todo: TodoDeclaration;
/** Meta data associated with the current process. */
export const meta: MetaInterface;