Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lukesavefrogs/jest-failfast

A configurable Jest Environment to allow for finer grade control over the way Jest handles failed tests.
https://github.com/lukesavefrogs/jest-failfast

bdd circus fail failfast fast jest jest-environment steps

Last synced: 24 days ago
JSON representation

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

Awesome Lists containing this project

README 

        


	
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**](https://www.npmjs.com/package/jest-environment-steps) and [**this S.O. answer**](https://stackoverflow.com/questions/51250006/jest-stop-test-suite-after-first-fail/65904327#65904327).



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**](https://www.npmjs.com/package/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:

```Javascript

/**

 * This tells Jest to use our custom Environment for this specific file.

 * 

 * @jest-environment /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](https://github.com/ysfaran) for [this SO answer](https://stackoverflow.com/a/65904327/8965861).

> 

Use this method to specify a [custom function](https://jestjs.io/docs/configuration#testenvironment-string#:~:text=handleTestEvent) 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**:

```Javascript

// 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](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Circus.ts). 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](https://stackoverflow.com/questions/51250006/jest-stop-test-suite-after-first-fail/65904327#65904327)

- [This package](https://www.npmjs.com/package/jest-environment-steps), which corresponds to this package with the `{ failFast: {enabled: true, scope: "global"} }` configuration.