Skip to content

A configurable Jest Environment to allow for finer grade control over the way Jest handles failed tests.

License

Notifications You must be signed in to change notification settings

LukeSavefrogs/jest-failfast

Repository files navigation

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 nameDescriptionTypeDefault
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 nameDescription
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 nameDescription
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 nameDescription
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.