FailFast

A configurable Jest Environment

Description

This package allows to have more control over the way Jest handles failed tests.

It has been inspired by Jest Environment Steps and this S.O. answer.

Quoting from "Jest Environment Steps" > Overview:

"In Jest, all tests with in a describe block run sequentially in the order of their appearance. But if a tests fails, the next tests continue to execute.

For writing tests for a behaviour where each test depends on success of previous test, this built-in feature may cause unnecessory tests to run

Example of behaviour tests.

Testing a CRUD apis on a database. Writing test for Create, Read, Update and Delete in the same sequence makes the it sense to test all apis in same order. and if Create fails, there is no pointing testing if the read, update and delete."

Jest FailFast has the same functionality, and some more useful features.

Features

• Global (as in Jest Environment Steps) or block-scoped test failures;
• Mark describe blocks as optional (if a failure happens it does not propagate)

Configuration

To use it, you just need to add the following lines at the top of the test file:

/**
 * This tells Jest to use our custom Environment for this specific file.
 * 
 * @jest-environment <rootDir>/src/jest-environment.js
 * @jest-environment-options { "failFast": {"enabled": true, "scope": "global"} }
 */

From there, you'll be able to change the configuration using the following schema:

Option name	Description	Type	Default
verbose	If set to true increases the verbosity of the messages printed on screen. Used for debugging.	Boolean	false
failFast.enabled	Wether to enable the failFast option or not. Setting it to false fallbacks to the original Jest behaviour.	Boolean	false
failFast.scope	The scope of the failure: global: A single test failure will cause the entire test suite to fail. block: A single test failure will cause to fail only the nearest describe block to fail. All subsequent tests inside that block will be skipped. Takes effect only if failFast.enabled is set to true.	"global"|"block"	global

Methods

testEnvironment.markBlockAsOptional()

Marks the current describe block as "optional". This means that any test failure inside that block won't cause a test suite failure even if failFast.scope is set to global.

This is used when you don't want that block status to influence the test suite exit code (i.e. some preconditions or tests that may fail).

testEnvironment.setVerbose(boolean)

Programmatically set the verbose option.

testEnvironment.registerTestEventHandler(function)

Originally made by @ysfaran for this SO answer.

Use this method to specify a custom function that will be called for every event fired by Jest.

Example

In the following example it will be called the takeScreenshot() function whenever a test fails:

// The `testEnvironment` variable is globally available
testEnvironment.registerTestEventHandler(async (event, state) => {
	if (event.name === "test_fn_failure") {
		await takeScreenshot()
	}
})

Events

The up-to-date list of events can be found here. These are the ones i found most useful:

Test suite
Event name	Description
setup	First event to be fired. Can be used to define a constructor of sorts.
teardown	Last event to be fired. Fired after everything is finished. Can be used to define a destructor of sorts.

test block
Event name	Description
test_start	A test has started.
test_skip	A test has been skipped.
test_fn_start	Fired when the function passed to a test starts.
test_fn_failure	Fired when the function passed to a test fails.
test_fn_success	Fired when the function passed to a test succeeds.

describe block
Event name	Description
run_describe_start	Fired when a describe block starts.
run_describe_finish	Fired when a describe block ends.

Sources

• This answer
• This package, which corresponds to this package with the { failFast: {enabled: true, scope: "global"} } configuration.