Skip to content
Permalink
main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
The notion of callback mode was removed in v4, the remaining references to it in the documentation may confuse users.
5 contributors

Users who have contributed to this file

@forresst @jasonritchie @novemberborn @ulken @ericcornelissen

Test setup

Translations: Fran莽ais

Tests can be set up using the beforeEach() hook. Often though you could use a plain setup function instead. This recipe helps you decide what's best for your use case.

The beforeEach() hook versus setup functions

The beforeEach() hook has some downsides. For example, you cannot turn it off for specific tests, nor can you apply it to specific tests. As an alternative, you can use simple functions. This allows you to use multiple setup functions for different setup requirements and call different parts of setup from different tests. You can even have setup functions with parameters so tests can customize their own setup.

Let's say you have a function that interacts with the file system. Perhaps you run a few tests using mock-fs, and then a few that use the real file system and a temporary directory. Or you have a setup function that you run with valid data for some tests and invalid data for other tests, all within the same test file.

You could do all these things using plain setup functions, but there are tradeoffs:

beforeEach() Setup functions
鉀旓笍 聽 used for all tests 聽 can change or skip depending on test
鉀旓笍 聽 more overhead for beginners, "some magic" 聽 easier for beginners, "no magic"
聽 built-in support for observables 鉀旓笍 聽 must use promises for asynchronous behavior
聽 failure has friendly output 鉀旓笍 聽 errors are attributed to the test
聽 corresponding afterEach and afterEach.always for cleanup 鉀旓笍 聽 cannot easily clean up

Complex test setup

In this example, we have both a beforeEach() hook, and then more modifications within each test.

test.beforeEach(t => {
	setupConditionA(t);
	setupConditionB(t);
	setupConditionC(t);
});

test('first scenario', t => {
	tweakSomething(t);
	const someCondition = t.context.thingUnderTest();
	t.true(someCondition);
});

test('second scenario', t => {
	tweakSomethingElse(t);
	const someOtherCondition = t.context.thingUnderTest();
	t.true(someOtherCondition);
});

If too many variables need changing for each test, consider omitting the beforeEach() hook and performing setup steps within the tests themselves.

test('first scenario', t => {
	setupConditionA(t);
	setupConditionB(t, {/* options */});
	setupConditionC(t);
	const someCondition = t.context.thingUnderTest();
	t.true(someCondition);
});

// In this test, setupConditionB() is never called.
test('second scenario', t => {
	setupConditionA(t);
	setupConditionC(t);
	const someOtherCondition = t.context.thingUnderTest();
	t.true(someOtherCondition);
});

You can use t.teardown() to register a teardown function which will run after the test has finished (regardless of whether it's passed or failed).

A practical example

test.beforeEach(t => {
	t.context = {
		authenticator: new Authenticator(),
		credentials: new Credentials('admin', 's3cr3t')
	};
});

test('authenticating with valid credentials', async t => {
	const isValid = t.context.authenticator.authenticate(t.context.credentials);
	t.true(await isValid);
});

test('authenticating with an invalid username', async t => {
	t.context.credentials.username = 'bad_username';
	const isValid = t.context.authenticator.authenticate(t.context.credentials);
	t.false(await isValid);
});

test('authenticating with an invalid password', async t => {
	t.context.credentials.password = 'bad_password';
	const isValid = t.context.authenticator.authenticate(t.context.credentials);
	t.false(await isValid);
});

The same tests, now using setup functions, would look like the following.

function setup({username = 'admin', password = 's3cr3t'} = {}) {
	return {
		authenticator: new Authenticator(),
		credentials: new Credentials(username, password)
	};
}

test('authenticating with valid credentials', async t => {
	const {authenticator, credentials} = setup();
	const isValid = authenticator.authenticate(credentials);
	t.true(await isValid);
});

test('authenticating with an invalid username', async t => {
	const {authenticator, credentials} = setup({username: 'bad_username'});
	const isValid = authenticator.authenticate(credentials);
	t.false(await isValid);
});

test('authenticating with an invalid password', async t => {
	const {authenticator, credentials} = setup({password: 'bad_password'});
	const isValid = authenticator.authenticate(credentials);
	t.false(await isValid);
});

Combining hooks and setup functions

Of course beforeEach() and plain setup functions can be used together:

test.beforeEach(t => {
	t.context = setupAllTests();
});

test('first scenario', t => {
	firstSetup(t);
	const someCondition = t.context.thingUnderTest();
	t.true(someCondition);
});