feat: support test environment options in docblocks (#12470)

jestjs · Feb 23, 2022 · 5e5a9ba · 5e5a9ba
1 parent 0523bcc
commit 5e5a9ba
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,7 @@
 - `[jest-resolve]` [**BREAKING**] Add support for `package.json` `exports` ([#11961](https://github.com/facebook/jest/pull/11961), [#12373](https://github.com/facebook/jest/pull/12373))
 - `[jest-resolve, jest-runtime]` Add support for `data:` URI import and mock ([#12392](https://github.com/facebook/jest/pull/12392))
 - `[jest-resolve, jest-runtime]` Add support for async resolver ([#11540](https://github.com/facebook/jest/pull/11540))
+- `[jest-runner]` Allow passing `testEnvironmentOptions` via docblocks ([#12470](https://github.com/facebook/jest/pull/12470))
 - `[@jest/schemas]` New module for JSON schemas for Jest's config ([#12384](https://github.com/facebook/jest/pull/12384))
 - `[jest-worker]` [**BREAKING**] Allow only absolute `workerPath` ([#12343](https://github.com/facebook/jest/pull/12343))
 - `[pretty-format]` New `maxWidth` parameter ([#12402](https://github.com/facebook/jest/pull/12402))

diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -1170,6 +1170,19 @@ Default: `{}`
 
 Test environment options that will be passed to the `testEnvironment`. The relevant options depend on the environment. For example, you can override options given to [`jsdom`](https://github.com/jsdom/jsdom) such as `{html: "<html lang="zh-cmn-Hant"></html>", url: 'https://jestjs.io/', userAgent: "Agent/007"}`.
 
+These options can also be passed in a docblock, similar to `testEnvironment`. Note that it must be parseable by `JSON.parse`. Example:
+
+```js
+/**
+ * @jest-environment jsdom
+ * @jest-environment-options {"url": "https://jestjs.io/"}
+ */
+
+test('use jsdom and set the URL in this test file', () => {
+  expect(window.location.href).toBe('https://jestjs.io/');
+});
+```
+
 ### `testFailureExitCode` \[number]
 
 Default: `1`

diff --git a/e2e/__tests__/testEnvironment.test.ts b/e2e/__tests__/testEnvironment.test.ts
@@ -23,7 +23,7 @@ it('respects testEnvironment docblock', () => {
   const {json: result} = runWithJson('test-environment');
 
   expect(result.success).toBe(true);
-  expect(result.numTotalTests).toBe(3);
+  expect(result.numTotalTests).toBe(4);
 });
 
 it('handles missing `mocked` property', () => {

diff --git a/e2e/test-environment/__tests__/environmentOptionsFromDocblock.test.js b/e2e/test-environment/__tests__/environmentOptionsFromDocblock.test.js
@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @jest-environment jsdom
+ * @jest-environment-options {"url": "https://jestjs.io/"}
+ */
+'use strict';
+/*eslint-env browser */
+
+test('use jsdom and set the URL in this test file', () => {
+  expect(window.location.href).toBe('https://jestjs.io/');
+});
diff --git a/packages/jest-runner/src/runTest.ts b/packages/jest-runner/src/runTest.ts
@@ -139,10 +139,27 @@ async function runTestInternal(
     testConsole = new BufferedConsole();
   }
 
+  let extraTestEnvironmentOptions;
+
+  const docblockEnvironmentOptions =
+    docblockPragmas['jest-environment-options'];
+
+  if (typeof docblockEnvironmentOptions === 'string') {
+    extraTestEnvironmentOptions = JSON.parse(docblockEnvironmentOptions);
+  }
+
   const environment = new TestEnvironment(
     {
       globalConfig,
-      projectConfig,
+      projectConfig: extraTestEnvironmentOptions
+        ? {
+            ...projectConfig,
+            testEnvironmentOptions: {
+              ...projectConfig.testEnvironmentOptions,
+              ...extraTestEnvironmentOptions,
+            },
+          }
+        : projectConfig,
     },
     {
       console: testConsole,