Add test.macro(), change how macros are typed

Fixes #2189. `test.macro()` returns an object that can be used with
`test()` and hooks. The `t.context` type is inherited from `test`.

Like with AVA 3, regular functions that also have a `title` property
that is a string-returning function are supported. However this is no
longer in the type definition.

Instead the recommended approach is to use `test.macro()` to declare
macros. At a TypeScript level these are easier to discriminate from
regular implementations.

Author: novemberborn

.xo-config.json

@@ -71,6 +71,12 @@
 				"import/no-extraneous-dependencies": "off",
 				"import/no-unresolved": "off"
 			}
+		},
+		{
+			"files": "test/macros/fixtures/macros.js",
+			"rules": {
+				"ava/no-identical-title": "off"
+			}
 		}
 	]
 }

docs/01-writing-tests.md

@@ -294,6 +294,8 @@ console.log('Test file currently being run:', test.meta.file);
 
 Additional arguments passed to the test declaration will be passed to the test implementation. This is useful for creating reusable test macros.
 
+You can use plain functions:
+
 ```js
 function macro(t, input, expected) {
 	t.is(eval(input), expected);
@@ -303,7 +305,7 @@ test('2 + 2 = 4', macro, '2 + 2', 4);
 test('2 * 3 = 6', macro, '2 * 3', 6);
 ```
 
-You can build the test title programmatically by attaching a `title` function to the macro:
+With AVA 3 you can build the test title programmatically by attaching a `title` function to the macro:
 
 ```js
 function macro(t, input, expected) {
@@ -319,4 +321,35 @@ test('providedTitle', macro, '3 * 3', 9);
 
 The `providedTitle` argument defaults to `undefined` if the user does not supply a string title. This means you can use a parameter assignment to set the default value. The example above uses the empty string as the default.
 
+However with AVA 4 the preferred approach is to use the `test.macro()` helper:
+
+```js
+import test from 'ava';
+
+const macro = test.macro((t, input, expected) => {
+	t.is(eval(input), expected);
+});
+
+test('title', macro, '3 * 3', 9);
+```
+
+Or with a title function:
+
+```js
+import test from 'ava';
+
+const macro = test.macro({
+	exec(t, input, expected) {
+		t.is(eval(input), expected);
+	},
+	title(providedTitle = '', input, expected) {
+		return `${providedTitle} ${input} = ${expected}`.trim();
+	}
+});
+
+test(macro, '2 + 2', 4);
+test(macro, '2 * 3', 6);
+test('providedTitle', macro, '3 * 3', 9);
+```
+
 We encourage you to use macros instead of building your own test generators ([here is an example](https://github.com/avajs/ava-codemods/blob/47073b5b58aa6f3fb24f98757be5d3f56218d160/test/ok-to-truthy.js#L7-L9) of code that should be replaced with a macro). Macros are designed to perform static analysis of your code, which can lead to better performance, IDE integration, and linter rules.

docs/recipes/typescript.md

@@ -121,7 +121,9 @@ const hasLength = (t: ExecutionContext, input: string, expected: number) => {
 test('bar has length 3', hasLength, 'bar', 3);
 ```
 
-In order to be able to assign the `title` property to a macro you need to type the function:
+### AVA 3
+
+With AVA 3, in order to be able to assign the `title` property to a macro you need to type the function:
 
 ```ts
 import test, {Macro} from 'ava';
@@ -149,6 +151,39 @@ const macro: CbMacro<[]> = t => {
 test.cb(macro);
 ```
 
+### AVA 4
+
+With AVA 4 you can use the `test.macro()` helper to create macros:
+
+```ts
+import test from 'ava';
+
+const macro = test.macro((t, input: string, expected: number) => {
+	t.is(eval(input), expected);
+});
+
+test('title', macro, '3 * 3', 9);
+```
+
+Or with a title function:
+
+```ts
+import test from 'ava';
+
+const macro = test.macro({
+	exec(t, input: string, expected: number) {
+		t.is(eval(input), expected);
+	},
+	title(providedTitle = '', input, expected) {
+		return `${providedTitle} ${input} = ${expected}`.trim();
+	}
+});
+
+test(macro, '2 + 2', 4);
+test(macro, '2 * 3', 6);
+test('providedTitle', macro, '3 * 3', 9);
+```
+
 ## Typing [`t.context`](../01-writing-tests.md#test-context)
 
 By default, the type of `t.context` will be the empty object (`{}`). AVA exposes an interface `TestInterface<Context>` which you can use to apply your own type to `t.context`. This can help you catch errors at compile-time:

index.d.ts

@@ -401,19 +401,37 @@ export interface TeardownFn {
 	(fn: () => void): void;
 }
 
+export type ImplementationFn<Args extends any[], 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 any[]> = (providedTitle: string | undefined, ...args: Args) => string;
+
+/** A reusable test or hook implementation. */
+export type Macro<Args extends any[], 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 any[], Context = unknown> = ImplementationFn<Args, Context> | Macro<Args, Context>;
+
 export interface TryFn<Context = unknown> {
 	/**
 	 * Attempt to run some assertions. The result must be explicitly committed or discarded or else
-	 * the test will fail. A macro may be provided. The title may help distinguish attempts from
-	 * one another.
+	 * the test will fail. The title may help distinguish attempts from one another.
 	 */
-	<Args extends any[]>(title: string, fn: EitherMacro<Args, Context>, ...args: Args): Promise<TryResult>;
+	<Args extends any[]>(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. A macro may be provided.
+	 * the test will fail.
 	 */
-	<Args extends any[]>(fn: EitherMacro<Args, Context>, ...args: Args): Promise<TryResult>;
+	<Args extends any[]>(fn: Implementation<Args, Context>, ...args: Args): Promise<TryResult>;
 }
 
 export interface AssertionError extends Error {}
@@ -451,34 +469,15 @@ export interface TryResult {
 	discard(options?: CommitDiscardOptions): void;
 }
 
-// FIXME(novemberborn) Refactor implementations to be different types returning a promise,, subscribable, or void, not a
-// single type returning a union. A union with void as a return type doesn't make sense.
-export type ImplementationResult = PromiseLike<void> | Subscribable | boolean | void;
-export type Implementation<Context = unknown> = (t: ExecutionContext<Context>) => ImplementationResult;
-
-/** A reusable test or hook implementation. */
-export type UntitledMacro<Args extends any[], Context = unknown> = (t: ExecutionContext<Context>, ...args: Args) => ImplementationResult;
+export interface TestInterface<Context = unknown> {
+	/** Declare a concurrent test. Additional arguments are passed along. */
+	<Args extends any[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
 
-/** A reusable test or hook implementation. */
-export type Macro<Args extends any[], Context = unknown> = UntitledMacro<Args, Context> & {
 	/**
-	 * 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.
+	 * Declare a concurrent test that uses a macro. The macro is responsible for generating a unique test title.
+	 * Additional arguments are passed along.
 	 */
-	title?: (providedTitle: string | undefined, ...args: Args) => string;
-};
-
-export type EitherMacro<Args extends any[], Context> = Macro<Args, Context> | UntitledMacro<Args, Context>;
-
-export interface TestInterface<Context = unknown> {
-	/** Declare a concurrent test. */
-	(title: string, implementation: Implementation<Context>): void;
-
-	/** Declare a concurrent test that uses a macro. Additional arguments are passed to the macro. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/** Declare a concurrent test that uses a macro. The macro is responsible for generating a unique test title. */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	<Args extends any[]>(macro: Macro<Args, Context>, ...args: Args): void;
 
 	/** Declare a hook that is run once, after all tests have passed. */
 	after: AfterInterface<Context>;
@@ -501,21 +500,16 @@ export interface TestInterface<Context = unknown> {
 	only: OnlyInterface<Context>;
 	skip: SkipInterface<Context>;
 	todo: TodoDeclaration;
+	macro: MacroDeclaration<Context>;
 	meta: MetaInterface;
 }
 
 export interface AfterInterface<Context = unknown> {
-	/** Declare a hook that is run once, after all tests have passed. */
-	(implementation: Implementation<Context>): void;
+	/** Declare a hook that is run once, after all tests have passed. Additional arguments are passed along. */
+	<Args extends any[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
 
-	/** Declare a hook that is run once, after all tests have passed. */
-	(title: string, implementation: Implementation<Context>): void;
-
-	/** Declare a hook that is run once, after all tests have passed. Additional arguments are passed to the macro. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/** Declare a hook that is run once, after all tests have passed. */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	/** Declare a hook that is run once, after all tests have passed. Additional arguments are passed along. */
+	<Args extends any[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
 
 	/** Declare a hook that is run once, after all tests are done. */
 	always: AlwaysInterface<Context>;
@@ -524,99 +518,66 @@ export interface AfterInterface<Context = unknown> {
 }
 
 export interface AlwaysInterface<Context = unknown> {
-	/** Declare a hook that is run once, after all tests are done. */
-	(implementation: Implementation<Context>): void;
-
-	/** Declare a hook that is run once, after all tests are done. */
-	(title: string, implementation: Implementation<Context>): void;
+	/** Declare a hook that is run once, after all tests are done. Additional arguments are passed along. */
+	<Args extends any[]>(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 macro. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/** Declare a hook that is run once, after all tests are done. */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	/** Declare a hook that is run once, after all tests are done. Additional arguments are passed along. */
+	<Args extends any[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
 
 	skip: HookSkipInterface<Context>;
 }
 
 export interface BeforeInterface<Context = unknown> {
-	/** Declare a hook that is run once, before all tests. */
-	(implementation: Implementation<Context>): void;
+	/** Declare a hook that is run once, before all tests. Additional arguments are passed along. */
+	<Args extends any[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
 
-	/** Declare a hook that is run once, before all tests. */
-	(title: string, implementation: Implementation<Context>): void;
-
-	/** Declare a hook that is run once, before all tests. Additional arguments are passed to the macro. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/** Declare a hook that is run once, before all tests. */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	/** Declare a hook that is run once, before all tests. Additional arguments are passed along. */
+	<Args extends any[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
 
 	skip: HookSkipInterface<Context>;
 }
 
 export interface FailingInterface<Context = unknown> {
-	/** Declare a concurrent test. The test is expected to fail. */
-	(title: string, implementation: Implementation<Context>): void;
+	/** Declare a concurrent test. Additional arguments are passed along. The test is expected to fail. */
+	<Args extends any[]>(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 test is expected to fail.
+	 * Declare a concurrent test that uses a macro. Additional arguments are passed along.
+	 * The macro is responsible for generating a unique test title. The test is expected to fail.
 	 */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/**
-	 * Declare a concurrent test that uses a macro. The macro is responsible for generating a unique test title.
-	 * The test is expected to fail.
-	 */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	<Args extends any[]>(macro: Macro<Args, Context>, ...args: Args): void;
 
 	only: OnlyInterface<Context>;
 	skip: SkipInterface<Context>;
 }
 
 export interface HookSkipInterface<Context = unknown> {
 	/** Skip this hook. */
-	(implementation: Implementation<Context>): void;
-
-	/** Skip this hook. */
-	(title: string, implementation: Implementation<Context>): void;
+	<Args extends any[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
 
 	/** Skip this hook. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/** Skip this hook. */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	<Args extends any[]>(implementation: Implementation<Args, Context>, ...args: Args): void;
 }
 
 export interface OnlyInterface<Context = unknown> {
-	/** Declare a test. Only this test and others declared with `.only()` are run. */
-	(title: string, implementation: Implementation<Context>): void;
-
-	/**
-	 * Declare a test that uses a macro. Additional arguments are passed to the macro.
-	 * Only this test and others declared with `.only()` are run.
-	 */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
+	/** Declare a test. Additional arguments are passed along. Only this test and others declared with `.only()` are run. */
+	<Args extends any[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
 
 	/**
 	 * Declare a test that uses a macro. The macro is responsible for generating a unique test title.
 	 * Only this test and others declared with `.only()` are run.
 	 */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	<Args extends any[]>(macro: Macro<Args, Context>, ...args: Args): void;
 }
 
 export interface SerialInterface<Context = unknown> {
-	/** Declare a serial test. */
-	(title: string, implementation: Implementation<Context>): void;
-
-	/** Declare a serial test that uses a macro. Additional arguments are passed to the macro. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
+	/** Declare a serial test. Additional arguments are passed along. */
+	<Args extends any[]>(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.
 	 */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	<Args extends any[]>(macro: Macro<Args, Context>, ...args: Args): void;
 
 	/** Declare a serial hook that is run once, after all tests have passed. */
 	after: AfterInterface<Context>;
@@ -640,20 +601,28 @@ export interface SerialInterface<Context = unknown> {
 
 export interface SkipInterface<Context = unknown> {
 	/** Skip this test. */
-	(title: string, implementation: Implementation<Context>): void;
+	<Args extends any[]>(title: string, implementation: Implementation<Args, Context>, ...args: Args): void;
 
 	/** Skip this test. */
-	<T extends any[]>(title: string, macro: EitherMacro<T, Context>, ...rest: T): void;
-
-	/** Skip this test. */
-	<T extends any[]>(macro: EitherMacro<T, Context>, ...rest: T): void;
+	<Args extends any[]>(macro: Macro<Args, Context>, ...args: Args): void;
 }
 
 export interface TodoDeclaration {
 	/** Declare a test that should be implemented later. */
 	(title: string): void;
 }
 
+export type MacroDeclarationOptions<Args extends any[], Context = unknown> = {
+	exec: ImplementationFn<Args, Context>;
+	title: TitleFn<Args>;
+};
+
+export interface MacroDeclaration<Context = unknown> {
+	/** Declare a reusable test implementation. */
+	<Args extends any[]>(exec: ImplementationFn<Args, Context>): Macro<Args, Context>;
+	<Args extends any[]>(declaration: MacroDeclarationOptions<Args, Context>): Macro<Args, Context>;
+}
+
 export interface MetaInterface {
 	/** Path to the test file being executed. */
 	file: string;

lib/create-chain.js

@@ -91,6 +91,14 @@ export default function createChain(fn, defaults, meta) {
 	root.todo = startChain('test.todo', fn, {...defaults, type: 'test', todo: true});
 	root.serial.todo = startChain('test.serial.todo', fn, {...defaults, serial: true, type: 'test', todo: true});
 
+	root.macro = options => {
+		if (typeof options === 'function') {
+			return Object.freeze({exec: options});
+		}
+
+		return Object.freeze({exec: options.exec, title: options.title});
+	};
+
 	root.meta = meta;
 
 	return root;