Skip to content

Latest commit

 

History

History
143 lines (90 loc) · 8.93 KB

Guide.Jest.md

File metadata and controls

143 lines (90 loc) · 8.93 KB

Jest

This guide describes how to install Jest as the test runner to be used by Detox for effectively running the E2E tests (i.e. instead of the default runner, which is Mocha).

Disclaimer

  • The guide describes installing Detox with Jest on a fresh project. If you're migrating an existing project, use the guide but please apply some common sense in the process.

  • The guide has been officially tested only with Jest 24.x.x. We cannot guarantee that everything would work with older versions.

Introduction

As already mentioned in the Getting Started guide, Detox itself does not effectively run tests logic, but rather delegates that responsibility onto a test runner. Jest is the recommended runner for projects with test suites that have become large enough so as to require parallel execution.

Do note that in turn, Jest itself - much like Detox, also does not effectively run any tests; Rather, it is more of a dispatcher and orchestrator of multiple instances of a delegated runner, capable of running in parallel (for more info, refer to this video; source: Jest architecture). Currently, by default, the concrete runner is jasmine v2, but Jest's own project called jest-circus is becoming more and more stable. In a way, we even recommend using it over jasmine because of bugs in jasmine that are not maintained (this one in particular).

The guide initially describes the setup of Jest in its default settings (i.e. using jasmine). For applying jest-circus, refer to the end of the installation section.

Installation

0. Set up Detox' fundamentals

Before starting out with Jest, please be sure to go over the fundamentals of the Getting Started guide.

1. Install Jest

npm install --save-dev jest

2. Set up test-code scaffolds

Run an automated init script:

detox init -r jest

Errors occurring in the process may appear in red.

Fix & Verify

Even if detox init goes well and everything is green, we recommend going over some fundamental things, using our homebrewed demo-react-native-jest example project as a reference.

a. Fix/verify this list of JSON properties:
File Property Value Description
package.json detox.test-runner "jest" Required. Should be "jest" for the proper detox test CLI functioning.
detox.runner-config (optional path to Jest config file) Optional. This field tells detox test CLI where to look for Jest's config file. If omitted, the path defaults to "e2e/config.json" (a file generated by detox init -r jest).
e2e/config.json testEnvironment "node" Required. Needed for the proper functioning of Jest and Detox.
setupFilesAfterEnv ["./init.js"] Required. Indicates which files to run before each test suite. The field was introduced in Jest 24.
reporters ["detox/runners/
jest/streamlineReporter"]		 Optional. Available since Detox 12.7.0. Sets up our highly recommended streamline-reporter Jest reporter, tailored for running end-to-end tests in Jest - which in itself was mostly intended for running unit tests. For more details, see the migration guide.
verbose true Must be true if you have replaced Jest's default reporter with Detox's streamlineReporter. Optional otherwise.

A typical detox configuration in a package.jsonfile:

package.json

b. Fix/verify the custom Jest init script (i.e. e2e/init.js):
  • beforeAll(), beforeEach(), afterAll() should be registered as hooks for invoking detox and/or a custom adapter.
  • The custom Detox-Jest adapter must be registered as a jasmine reporter (jasmine.getEnv().addReporter()). It is required for the artifacts subsystem to properly work.
  • (Recommended) Starting Detox 12.7.0, an additional, custom spec-reporter should be registered as a jasmine reporter, as well. This one takes care of logging on a per-spec basis (i.e. when it's start and end) — which Jest does not do by default. Should be used in conjunction with the Detox-Jest adapter.

A typical Jest log output, having set up streamline-reporter in config.json and spec-reporter in init.js:

Streamlined output

3. Applying jest-circus (optional)

  • Experimental; Frequent breaking changes are expected in upcoming versions! Known issues:
    • Video recording causes iOS simulator to freeze
  • Requires Detox >= 14.3.0 !!!
  • Tested on Jest & jest-circus version >= 24.8.0 !!!

By reaching this point you effectively have Jest set up and ready to launch in its default settings - i.e. with jasmine as its default test runner. However, jasmine can be switched with jest-circus as a drop-in replacement. To do so, apply these changes:

a. Install jest-circus
npm install --save-dev jest-circus

Make sure jest and jest-circus' versions match (e.g. both are 24.9.0)

b. Update jest's config

In e2e/config.json, apply this change:

// e2e/config.json

{
-    "testEnvironment": "node"
+    "testEnvironment": "detox/runners/jest/JestCircusEnvironment",
+    "testRunner": "jest-circus/runner"

...
}
c. Update init script

In e2e/init.js, as explained in the previous section, we typically register the main adapter and various reporters directly do jasmine. Since jest-circus replaces jasmine, we've set up a custom circus-associated API to replace jasmine.getEnv().addReporter() calls, namely: detoxCircus.getEnv().addEventsListener(). You must have all associated calls replaced. Example:

// e2e/init.js

const adapter = require('detox/runners/jest/adapter');
const specReporter = require('detox/runners/jest/specReporter');
const assignReporter = require('detox/runners/jest/assignReporter');

-jasmine.getEnv().addReporter(adapter);
-jasmine.getEnv().addReporter(specReporter);
-jasmine.getEnv().addReporter(assignReporter);
+detoxCircus.getEnv().addEventsListener(adapter);
+detoxCircus.getEnv().addEventsListener(specReporter);
+detoxCircus.getEnv().addEventsListener(assignReporter);

Once again, use our jest demo-suite's init.js as a reference.

Writing Tests

There are some things you should notice:

  • Don't worry about mocks being used, Detox works on the compiled version of your app.
  • Detox exposes it's primitives (expect, device, ...) globally, it will override Jest's global expect object.

Parallel Test Execution

Through Detox' cli, Jest can be started with multiple workers that run tests simultaneously. In this mode, Jest effectively assigns one worker per each test file (invoking Jasmine over it). In this mode, the per-spec logging offered by the spec-reporter mentioned earlier, does not necessarily make sense, as the workers' outputs get mixed up.

By default, we disable spec-reporter in a multi-workers environment. If you wish to force-enable it nonetheless, the --jest-report-specs CLI option can be used.

How to run unit test and E2E tests in the same project

  • If you have a setup file for the unit tests pass ./jest/setup implementation into your unit setup.
  • Call your E2E tests using detox-cli: detox test