Remove test.cb()

Fixes #2387.

Author: novemberborn

docs/01-writing-tests.md

@@ -93,7 +93,9 @@ test('handles observables', t => {
 
 ## Callback support
 
-AVA supports using `t.end` as the final callback when using Node.js-style error-first callback APIs. AVA will consider any truthy value passed as the first argument to `t.end` to be an error. Note that `t.end` requires "callback mode", which can be enabled by using the `test.cb` chain.
+*👉 AVA 4 removes support for `test.cb()` and `t.end()`.*
+
+AVA 3 supports using `t.end` as the final callback when using Node.js-style error-first callback APIs. AVA will consider any truthy value passed as the first argument to `t.end` to be an error. Note that `t.end` requires "callback mode", which can be enabled by using the `test.cb` chain.
 
 ```js
 test.cb('data.txt can be read', t => {
@@ -223,7 +225,7 @@ test('title', t => {
 });
 ```
 
-Hooks can be synchronous or asynchronous, just like tests. To make a hook asynchronous return a promise or observable, use an async function, or enable callback mode via `test.before.cb()`, `test.beforeEach.cb()` etc.
+Hooks can be synchronous or asynchronous, just like tests. To make a hook asynchronous return a promise or observable, or use an async function.
 
 ```js
 test.before(async t => {
@@ -233,14 +235,6 @@ test.before(async t => {
 test.after(t => {
 	return new Promise(/* ... */);
 });
-
-test.beforeEach.cb(t => {
-	setTimeout(t.end);
-});
-
-test.afterEach.cb(t => {
-	setTimeout(t.end);
-});
 ```
 
 Keep in mind that the `.beforeEach()` and `.afterEach()` hooks run just before and after a test is run, and that by default tests run concurrently. This means each multiple `.beforeEach()` hooks may run concurrently. Using `test.serial.beforeEach()` does not change this. If you need to set up global state for each test (like spying on `console.log` [for example](https://github.com/avajs/ava/issues/560)), you'll need to make sure the tests themselves are [run serially](#running-tests-serially).

docs/02-execution-context.md

@@ -28,7 +28,7 @@ When used in `test.afterEach()` or `test.afterEach.always()` hooks this tells yo
 
 ## `t.end()`
 
-End the test. Only works with `test.cb()`.
+End the test. Only works with `test.cb()`. Removed in AVA 4.
 
 ## `t.log(...values)`
 

docs/03-assertions.md

@@ -41,15 +41,6 @@ test('resolves with 3', t => {
 		t.is(n, 3);
 	});
 });
-
-test.cb('invokes callback', t => {
-	t.plan(1);
-
-	someAsyncFunction(() => {
-		t.pass();
-		t.end();
-	});
-});
 ```
 
 These won't:

docs/08-common-pitfalls.md

@@ -39,22 +39,13 @@ test('fetches foo', async t => {
 });
 ```
 
-If you're using callbacks, use [`test.cb`](./01-writing-tests.md#callback-support):
+If you're using callbacks, promisify the callback function using something like [`util.promisify()`](https://nodejs.org/dist/latest/docs/api/util.html#util_util_promisify_original):
 
 ```js
-test.cb('fetches foo', t => {
-	fetch((err, data) => {
-		t.is(data, 'foo');
-		t.end();
-	});
-});
-```
-
-Alternatively, promisify the callback function using something like [`pify`](https://github.com/sindresorhus/pify):
+const {promisify} = require('util');
 
-```js
 test('fetches foo', async t => {
-	const data = await pify(fetch)();
+	const data = await promisify(fetch)();
 	t.is(data, 'foo');
 });
 ```

docs/recipes/typescript.md

@@ -136,7 +136,7 @@ test(macro, '2 * 3', 6);
 test('providedTitle', macro, '3 * 3', 9);
 ```
 
-You'll need a different type if you're expecting your macro to be used with a callback test:
+You'll need a different type if you're expecting your macro to be used with an AVA 3 callback test:
 
 ```ts
 import test, {CbMacro} from 'ava';
@@ -166,7 +166,7 @@ test.beforeEach(t => {
 	t.context.foo = 123; // error:  Type '123' is not assignable to type 'string'
 });
 
-test.serial.cb.failing('very long chains are properly typed', t => {
+test.serial.failing('very long chains are properly typed', t => {
 	t.context.fooo = 'a value'; // error: Property 'fooo' does not exist on type ''
 });
 

docs/recipes/when-to-use-plan.md

@@ -93,25 +93,6 @@ As stated in the previous example, using the `t.throws()` assertion with `async`
 
 `t.plan()` provides value in the following cases.
 
-### Ensuring multiple callbacks are actually called
-
-```js
-test.cb('invokes callbacks', t => {
-	t.plan(2);
-
-	const callbackA = () => {
-		t.pass();
-		t.end();
-	};
-
-	const callbackB = () => t.pass();
-
-	bThenA(callbackA, callbackB);
-});
-```
-
-The above ensures `callbackB` is called first (and only once), followed by `callbackA`. Any other combination would not satisfy the plan.
-
 ### Tests with branching statements
 
 In most cases, it's a bad idea to use any complex branching inside your tests. A notable exception is for tests that are auto-generated (perhaps from a JSON document). Below `t.plan()` is used to ensure the correctness of the JSON input:

index.d.ts

@@ -464,20 +464,10 @@ export interface TryResult {
 	discard(options?: CommitDiscardOptions): void;
 }
 
-/** The `t` value passed to implementations for tests & hooks declared with the `.cb` modifier. */
-export interface CbExecutionContext<Context = unknown> extends ExecutionContext<Context> {
-	/**
-	 * 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;
-}
-
 // 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;
-export type CbImplementation<Context = unknown> = (t: CbExecutionContext<Context>) => ImplementationResult;
 
 /** A reusable test or hook implementation. */
 export type UntitledMacro<Args extends any[], Context = unknown> = (t: ExecutionContext<Context>, ...args: Args) => ImplementationResult;
@@ -496,19 +486,6 @@ export type EitherMacro<Args extends any[], Context> = Macro<Args, Context> | Un
 /** Alias for a single macro, or an array of macros. */
 export type OneOrMoreMacros<Args extends any[], Context> = EitherMacro<Args, Context> | [EitherMacro<Args, Context>, ...Array<EitherMacro<Args, Context>>];
 
-/** A reusable test or hook implementation, for tests & hooks declared with the `.cb` modifier. */
-export type UntitledCbMacro<Args extends any[], Context = unknown> = (t: CbExecutionContext<Context>, ...args: Args) => ImplementationResult;
-
-/** A reusable test or hook implementation, for tests & hooks declared with the `.cb` modifier. */
-export type CbMacro<Args extends any[], Context = unknown> = UntitledCbMacro<Args, Context> & {
-	title?: (providedTitle: string | undefined, ...args: Args) => string;
-};
-
-export type EitherCbMacro<Args extends any[], Context> = CbMacro<Args, Context> | UntitledCbMacro<Args, Context>;
-
-/** Alias for a single macro, or an array of macros, used for tests & hooks declared with the `.cb` modifier. */
-export type OneOrMoreCbMacros<Args extends any[], Context> = EitherCbMacro<Args, Context> | [EitherCbMacro<Args, Context>, ...Array<EitherCbMacro<Args, Context>>];
-
 export interface TestInterface<Context = unknown> {
 	/** Declare a concurrent test. */
 	(title: string, implementation: Implementation<Context>): void;
@@ -531,9 +508,6 @@ export interface TestInterface<Context = unknown> {
 	/** Declare a hook that is run before each test. */
 	beforeEach: BeforeInterface<Context>;
 
-	/** Declare a test that must call `t.end()` when it's done. */
-	cb: CbInterface<Context>;
-
 	/** Declare a test that is expected to fail. */
 	failing: FailingInterface<Context>;
 
@@ -562,9 +536,6 @@ export interface AfterInterface<Context = unknown> {
 	/** Declare a hook that is run once, after all tests are done. */
 	always: AlwaysInterface<Context>;
 
-	/** Declare a hook that must call `t.end()` when it's done. */
-	cb: HookCbInterface<Context>;
-
 	skip: HookSkipInterface<Context>;
 }
 
@@ -581,9 +552,6 @@ export interface AlwaysInterface<Context = unknown> {
 	/** Declare a hook that is run once, after all tests are done. */
 	<T extends any[]>(macros: OneOrMoreMacros<T, Context>, ...rest: T): void;
 
-	/** Declare a hook that must call `t.end()` when it's done. */
-	cb: HookCbInterface<Context>;
-
 	skip: HookSkipInterface<Context>;
 }
 
@@ -600,85 +568,9 @@ export interface BeforeInterface<Context = unknown> {
 	/** Declare a hook that is run once, before all tests. */
 	<T extends any[]>(macros: OneOrMoreMacros<T, Context>, ...rest: T): void;
 
-	/** Declare a hook that must call `t.end()` when it's done. */
-	cb: HookCbInterface<Context>;
-
 	skip: HookSkipInterface<Context>;
 }
 
-export interface CbInterface<Context = unknown> {
-	/** Declare a test that must call `t.end()` when it's done. */
-	(title: string, implementation: CbImplementation<Context>): 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.
-	 */
-	<T extends any[]>(title: string, macros: OneOrMoreCbMacros<T, Context>, ...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.
-	 */
-	<T extends any[]>(macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-
-	/** Declare a test that is expected to fail. */
-	failing: CbFailingInterface<Context>;
-
-	only: CbOnlyInterface<Context>;
-	skip: CbSkipInterface<Context>;
-}
-
-export interface CbFailingInterface<Context = unknown> {
-	/** Declare a test that must call `t.end()` when it's done. The test is expected to fail. */
-	(title: string, implementation: CbImplementation<Context>): 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.
-	 */
-	<T extends any[]>(title: string, macros: OneOrMoreCbMacros<T, Context>, ...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.
-	 */
-	<T extends any[]>(macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-
-	only: CbOnlyInterface<Context>;
-	skip: CbSkipInterface<Context>;
-}
-
-export interface CbOnlyInterface<Context = unknown> {
-	/**
-	 * 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<Context>): 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.
-	 */
-	<T extends any[]>(title: string, macros: OneOrMoreCbMacros<T, Context>, ...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.
-	 */
-	<T extends any[]>(macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-}
-
-export interface CbSkipInterface<Context = unknown> {
-	/** Skip this test. */
-	(title: string, implementation: CbImplementation<Context>): void;
-
-	/** Skip this test. */
-	<T extends any[]>(title: string, macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-
-	/** Skip this test. */
-	<T extends any[]>(macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-}
-
 export interface FailingInterface<Context = unknown> {
 	/** Declare a concurrent test. The test is expected to fail. */
 	(title: string, implementation: Implementation<Context>): void;
@@ -699,41 +591,6 @@ export interface FailingInterface<Context = unknown> {
 	skip: SkipInterface<Context>;
 }
 
-export interface HookCbInterface<Context = unknown> {
-	/** Declare a hook that must call `t.end()` when it's done. */
-	(implementation: CbImplementation<Context>): void;
-
-	/** Declare a hook that must call `t.end()` when it's done. */
-	(title: string, implementation: CbImplementation<Context>): 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.
-	 */
-	<T extends any[]>(title: string, macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-
-	/**
-	 * Declare a hook that uses one or more macros. The macros must call `t.end()` when they're done.
-	 */
-	<T extends any[]>(macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-
-	skip: HookCbSkipInterface<Context>;
-}
-
-export interface HookCbSkipInterface<Context = unknown> {
-	/** Skip this hook. */
-	(implementation: CbImplementation<Context>): void;
-
-	/** Skip this hook. */
-	(title: string, implementation: CbImplementation<Context>): void;
-
-	/** Skip this hook. */
-	<T extends any[]>(title: string, macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-
-	/** Skip this hook. */
-	<T extends any[]>(macros: OneOrMoreCbMacros<T, Context>, ...rest: T): void;
-}
-
 export interface HookSkipInterface<Context = unknown> {
 	/** Skip this hook. */
 	(implementation: Implementation<Context>): void;
@@ -789,9 +646,6 @@ export interface SerialInterface<Context = unknown> {
 	/** Declare a serial hook that is run before each test. */
 	beforeEach: BeforeInterface<Context>;
 
-	/** Declare a serial test that must call `t.end()` when it's done. */
-	cb: CbInterface<Context>;
-
 	/** Declare a serial test that is expected to fail. */
 	failing: FailingInterface<Context>;
 
@@ -842,9 +696,6 @@ 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;
 

lib/create-chain.js

@@ -48,14 +48,10 @@ function createHookChain(hook, isAfterHook) {
 	// * `skip` must come at the end
 	// * no `only`
 	// * no repeating
-	extendChain(hook, 'cb', 'callback');
 	extendChain(hook, 'skip', 'skipped');
-	extendChain(hook.cb, 'skip', 'skipped');
 	if (isAfterHook) {
 		extendChain(hook, 'always');
-		extendChain(hook.always, 'cb', 'callback');
 		extendChain(hook.always, 'skip', 'skipped');
-		extendChain(hook.always.cb, 'skip', 'skipped');
 	}
 
 	return hook;
@@ -69,27 +65,15 @@ function createChain(fn, defaults, meta) {
 	// * `only` and `skip` cannot be chained together
 	// * no repeating
 	const root = startChain('test', fn, {...defaults, type: 'test'});
-	extendChain(root, 'cb', 'callback');
 	extendChain(root, 'failing');
 	extendChain(root, 'only', 'exclusive');
 	extendChain(root, 'serial');
 	extendChain(root, 'skip', 'skipped');
-	extendChain(root.cb, 'failing');
-	extendChain(root.cb, 'only', 'exclusive');
-	extendChain(root.cb, 'skip', 'skipped');
-	extendChain(root.cb.failing, 'only', 'exclusive');
-	extendChain(root.cb.failing, 'skip', 'skipped');
 	extendChain(root.failing, 'only', 'exclusive');
 	extendChain(root.failing, 'skip', 'skipped');
-	extendChain(root.serial, 'cb', 'callback');
 	extendChain(root.serial, 'failing');
 	extendChain(root.serial, 'only', 'exclusive');
 	extendChain(root.serial, 'skip', 'skipped');
-	extendChain(root.serial.cb, 'failing');
-	extendChain(root.serial.cb, 'only', 'exclusive');
-	extendChain(root.serial.cb, 'skip', 'skipped');
-	extendChain(root.serial.cb.failing, 'only', 'exclusive');
-	extendChain(root.serial.cb.failing, 'skip', 'skipped');
 	extendChain(root.serial.failing, 'only', 'exclusive');
 	extendChain(root.serial.failing, 'skip', 'skipped');