feat: drop jest<27.2.5 support (#3392)

BREAKING: please migrate your projects to Jest 28.x or 27.x

detox/package.json

@@ -44,7 +44,6 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-unicorn": "^39.0.0",
     "jest": "^27.0.0",
-    "jest-environment-node": "^27.0.0",
     "mockdate": "^2.0.1",
     "prettier": "1.7.0",
     "react-native": "0.67.2",
@@ -80,7 +79,7 @@
     "yargs-unparser": "^2.0.0"
   },
   "peerDependencies": {
-    "jest": "26.0.x - 26.4.x || ^26.5.2 || 27.x.x || 28.x.x"
+    "jest": "28.x.x || ^27.2.5"
   },
   "peerDependenciesMeta": {
     "jest": {
@@ -99,6 +98,7 @@
     "roots": [
       "node_modules",
       "src",
+      "runners",
       "local-cli"
     ],
     "testPathIgnorePatterns": [
@@ -146,7 +146,8 @@
       "src/utils/logger.js",
       "src/utils/pipeCommands.js",
       "src/utils/pressAnyKey.js",
-      "src/utils/shellUtils.js"
+      "src/utils/shellUtils.js",
+      "runners/jest-circus/utils/assertJestCircus27.js"
     ],
     "resetMocks": true,
     "resetModules": true,

detox/runners/jest-circus/environment.js

@@ -1,5 +1,5 @@
 // @ts-nocheck
-const maybeNodeEnvironment = require('jest-environment-node'); // eslint-disable-line node/no-unpublished-require
+const maybeNodeEnvironment = require('jest-environment-node'); // eslint-disable-line node/no-extraneous-require
 const NodeEnvironment = maybeNodeEnvironment.default || maybeNodeEnvironment;
 
 const DetoxError = require('../../src/errors/DetoxError');
@@ -8,7 +8,7 @@ const Timer = require('../../src/utils/Timer');
 const DetoxCoreListener = require('./listeners/DetoxCoreListener');
 const DetoxInitErrorListener = require('./listeners/DetoxInitErrorListener');
 const assertExistingContext = require('./utils/assertExistingContext');
-const assertJestCircus26 = require('./utils/assertJestCircus26');
+const { assertJestCircus27 } = require('./utils/assertJestCircus27');
 const wrapErrorWithNoopLifecycle = require('./utils/wrapErrorWithNoopLifecycle');
 
 const SYNC_CIRCUS_EVENTS = new Set([
@@ -24,7 +24,7 @@ const SYNC_CIRCUS_EVENTS = new Set([
  */
 class DetoxCircusEnvironment extends NodeEnvironment {
   constructor(config, context) {
-    super(assertJestCircus26(config), assertExistingContext(context));
+    super(assertJestCircus27(config), assertExistingContext(context));
 
     /** @private */
     this._timer = null;

detox/runners/jest-circus/reporters/DetoxReporter.js

@@ -1,13 +1,15 @@
-const DetoxStreamlineJestReporter = require('./DetoxStreamlineJestReporter');
+const { VerboseReporter: JestVerboseReporter } = require('@jest/reporters'); // eslint-disable-line node/no-extraneous-require
+
 const FailingTestsReporter = require('./FailingTestsReporter');
 
-class DetoxReporter extends DetoxStreamlineJestReporter {
+class DetoxReporter extends JestVerboseReporter {
   constructor(globalConfig) {
     super(globalConfig);
     this._failingTestsReporter = new FailingTestsReporter();
   }
 
   async onRunComplete(contexts, results) {
+    // @ts-ignore
     await super.onRunComplete(contexts, results);
     await this._failingTestsReporter.onRunComplete(contexts, results);
   }

detox/runners/jest-circus/utils/assertJestCircus27.js

@@ -0,0 +1,56 @@
+const fs = require('fs');
+const path = require('path');
+
+const semver = require('semver');
+
+const detoxPackageJson = require('../../../package.json');
+const DetoxRuntimeError = require('../../../src/errors/DetoxRuntimeError');
+
+function assertJestCircus27(maybeProjectConfig) {
+  const projectConfig = maybeProjectConfig.projectConfig || maybeProjectConfig;
+
+  if (!/jest-circus/.test(projectConfig.testRunner)) {
+    throw new DetoxRuntimeError({
+      message: 'Cannot continue without Jest Circus test runner underneath, exiting.',
+      hint: 'Make sure that in your Jest config you have no "testRunner" property or it is explicitly set to "jest-circus/runner".',
+      debugInfo: `The test runner powering your configuration is:\n${projectConfig.testRunner}`,
+    });
+  }
+
+  const circusPackageJson = path.join(path.dirname(projectConfig.testRunner), 'package.json');
+  if (!fs.existsSync(circusPackageJson)) {
+    throw new DetoxRuntimeError({
+      message: 'Check that you have an installed copy of "jest-circus" npm package, exiting.',
+      debugInfo: `Its package.json file is missing: ${circusPackageJson}`,
+    });
+  }
+
+  const circusVersion = require(circusPackageJson).version;
+  if (!circusVersion) {
+    throw new DetoxRuntimeError({
+      message: 'Check that you have an valid copy of "jest-circus" npm package, exiting.',
+      debugInfo: `Its package.json file has no "version" property. See:\n` + circusPackageJson,
+    });
+  }
+
+  assertSupportedVersion(circusVersion);
+
+  return maybeProjectConfig;
+}
+
+function assertSupportedVersion(actualVersion) {
+  const supportedRange = detoxPackageJson.peerDependencies.jest;
+  const minSupportedVersion = semver.minVersion(supportedRange);
+
+  if (semver.lt(actualVersion, minSupportedVersion)) {
+    throw new DetoxRuntimeError({
+      message: `Detected an unsupported jest@${actualVersion} version.`,
+      hint: `Please upgrade your Jest test runner to the supported range: ${supportedRange}.`
+    });
+  }
+}
+
+module.exports = {
+  assertJestCircus27,
+  assertSupportedVersion,
+};

detox/runners/jest-circus/utils/assertJestCircus27.test.js

@@ -0,0 +1,23 @@
+const { assertSupportedVersion } = require('./assertJestCircus27');
+
+describe('assertSupportedVersion', () => {
+  test.each([
+    ['27.2.5'],
+    ['27.2.6-prerelease.0'],
+    ['27.3.0'],
+    ['28.0.0-alpha.1'],
+    ['28.0.0'],
+    ['28.1.0'],
+    ['29.0.0-next.0'],
+    ['30.0.0'],
+  ])('should pass for %j', (version) => {
+    expect(() => assertSupportedVersion(version)).not.toThrow();
+  });
+
+  test.each([
+    ['26.0.0'],
+    ['27.2.4'],
+  ])('should throw an error for %j', (version) => {
+    expect(() => assertSupportedVersion(version)).toThrowError(/unsupported jest.*version/);
+  });
+});

detox/test/e2e/config.js

@@ -7,8 +7,8 @@ module.exports = {
   'globalTeardown': './test/e2e/global-teardown.js',
   'testTimeout': 120000,
   'reporters': process.env.DISABLE_JUNIT_REPORTER === '1'
-    ? ['<rootDir>/runners/jest/streamlineReporter']
-    : ['<rootDir>/runners/jest/streamlineReporter', '<rootDir>/test/node_modules/jest-junit'],
+    ? ['<rootDir>/runners/jest-circus/reporter']
+    : ['<rootDir>/runners/jest-circus/reporter', '<rootDir>/test/node_modules/jest-junit'],
   'verbose': true,
   'bail': false,
   'maxWorkers': Number(process.env.DEMO_MAX_WORKERS || '1'),

docs/Guide.Jest.md

@@ -17,14 +17,12 @@ As already mentioned in the [Getting Started](Introduction.GettingStarted.md#set
 
 By the way, Jest itself — much like Detox, also does not effectively run any tests. Instead, 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](https://youtu.be/3YDiloj8_d0?t=2127) (source: [Jest architecture](https://jestjs.io/docs/en/architecture)).
 
-For its part, Detox supports only one Jest’s concrete runner, which is [`jest-circus`](https://www.npmjs.com/package/jest-circus) ([ships by default with Jest since 27.0.0](https://jestjs.io/blog/2021/05/25/jest-27)). The former runner, `jest-jasmine2`, is deprecated due to specific bugs in the past, and architectural limitations at present.
-
 ### Installation
 
 **Disclaimer:**
 
 1. Here we focus on installing Detox on _new projects_. If you’re migrating a project with an existing Detox installation, please apply some common sense while using this guide.
-1. These instructions are relevant for `jest@^27.0.0` (and `jest@^26.0.1 + jest-circus@^26.0.1`). They should likely work for the newer `jest` versions too, but for **the older ones** (25.x, 24.x) — **they will not, due to blocking issues.**
+1. These instructions are relevant for `jest@^27.2.5` and `jest@28.x.x`. They should likely work for the newer `jest` versions too, but for **the older ones** (26.x, 25.x) — **they will not, due to blocking issues.**
 
 #### 1. Install Jest
 
@@ -38,7 +36,6 @@ npm install -D "jest@>=27.2.5"
 
 **NOTE:** The command will install the _latest Jest version_. However, `@>=27.2.5` addendum is recommended just to be on the safe side in a common scenario, when a `package-lock.json`
 generated by an official React Native project template limits Jest version to a very old `26.x`, maybe due to some optimization mechanism.
-Generally we recommend not to stay on outdated Jest versions for too long, e.g. `jest@27.2.5` will be the minimal version supported by Detox 20.
 
 #### 2. Set up Test-code Scaffolds
 

examples/demo-plugin/e2e/config.json

@@ -2,6 +2,6 @@
     "testEnvironment": "./environment",
     "testTimeout": 120000,
     "testRegex": "\\.test\\.js$",
-    "reporters": ["detox/runners/jest/streamlineReporter"],
+    "reporters": ["detox/runners/jest-circus/reporter"],
     "verbose": true
 }

examples/demo-react-native-jest/e2e/config.json

@@ -10,6 +10,6 @@
     "transform": {
       "\\.tsx?$": "ts-jest"
     },
-    "reporters": ["detox/runners/jest/streamlineReporter"],
+    "reporters": ["detox/runners/jest-circus/reporter"],
     "verbose": true
 }

examples/demo-react-native-jest/e2eExplicitRequire/config.json

@@ -6,6 +6,6 @@
     "transform": {
       "\\.tsx?$": "ts-jest"
     },
-    "reporters": ["detox/runners/jest/streamlineReporter"],
+    "reporters": ["detox/runners/jest-circus/reporter"],
     "verbose": true
 }