chore(jest-transform): refactor transformer API to reduce number of a…

…rguments (#10834)

CHANGELOG.md

@@ -19,6 +19,7 @@
 - `[jest-runtime]` [**BREAKING**] remove long-deprecated `jest.addMatchers`, `jest.resetModuleRegistry`, and `jest.runTimersToTime` ([#9853](https://github.com/facebook/jest/pull/9853))
 - `[jest-transform]` Show enhanced `SyntaxError` message for all `SyntaxError`s ([#10749](https://github.com/facebook/jest/pull/10749))
 - `[jest-transform]` [**BREAKING**] Refactor API to pass an options bag around rather than multiple boolean options ([#10753](https://github.com/facebook/jest/pull/10753))
+- `[jest-transform]` [**BREAKING**] Refactor API of transformers to pass an options bag rather than separate `config` and other options
 
 ### Chore & Maintenance
 

docs/CodeTransformation.md

@@ -0,0 +1,102 @@
+---
+id: code-transformation
+title: Code Transformation
+---
+
+Jest runs the code in your project as JavaScript, but if you use some syntax not supported by Node.js out of the box (such as JSX, types from TypeScript, Vue templates etc.) then you'll need to transform that code into plain JavaScript, similar to what you would do when building for browsers.
+
+Jest supports this via the [`transform` configuration option](Configuration.md#transform-objectstring-pathtotransformer--pathtotransformer-object).
+
+A transformer is a module that provides a synchronous function for transforming source files. For example, if you wanted to be able to use a new language feature in your modules or tests that aren't yet supported by Node, you might plug in one of many compilers that compile a future version of JavaScript to a current one.
+
+Jest will cache the result of a transformation and attempt to invalidate that result based on a number of factors, such as the source of the file being transformed and changing configuration.
+
+## Defaults
+
+Jest ships with one transformer out of the box - `babel-jest`. It will automatically load your project's Babel configuration and transform any file matching the following RegEx: `/\.[jt]sx?$/` meaning any `.js`, `.jsx`, `.ts` and `.tsx` file. In addition, `babel-jest` will inject the Babel plugin necessary for mock hoisting talked about in [ES Module mocking](ManualMocks.md#using-with-es-module-imports).
+
+If you override the `transform` configuration option `babel-jest` will no longer be active, and you'll need to add it manually if you wish to use Babel.
+
+## Writing custom transformers
+
+You can write you own transformer. The API of a transformer is as follows:
+
+```ts
+interface Transformer<OptionType = unknown> {
+  /**
+   * Indicates if the transformer is capabale of instrumenting the code for code coverage.
+   *
+   * If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented.
+   * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel.
+   */
+  canInstrument?: boolean;
+  createTransformer?: (options?: OptionType) => Transformer;
+
+  getCacheKey?: (
+    sourceText: string,
+    sourcePath: string,
+    options: TransformOptions,
+  ) => string;
+
+  process: (
+    sourceText: string,
+    sourcePath: string,
+    options: TransformOptions,
+  ) => TransformedSource;
+}
+
+interface TransformOptions {
+  config: Config.ProjectConfig;
+  /** A stringified version of the configuration - useful in cache busting */
+  configString: string;
+  instrument: boolean;
+  // names are copied from babel: https://babeljs.io/docs/en/options#caller
+  supportsDynamicImport: boolean;
+  supportsExportNamespaceFrom: boolean;
+  supportsStaticESM: boolean;
+  supportsTopLevelAwait: boolean;
+}
+
+type TransformedSource =
+  | {code: string; map?: RawSourceMap | string | null}
+  | string;
+
+// Config.ProjectConfig can be seen in in code [here](https://github.com/facebook/jest/blob/v26.6.3/packages/jest-types/src/Config.ts#L323)
+// RawSourceMap comes from [`source-map`](https://github.com/mozilla/source-map/blob/0.6.1/source-map.d.ts#L6-L12)
+```
+
+As can be seen, only `process` is mandatory to implement, although we highly recommend implementing `getCacheKey` as well, so we don't waste resources transpiling the same source file when we can read its previous result from disk. You can use [`@jest/create-cache-key-function`](https://www.npmjs.com/package/@jest/create-cache-key-function) to help implement it.
+
+Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
+
+### Examples
+
+### TypeScript with type checking
+
+While `babel-jest` by default will transpile TypeScript files, Babel will not verify the types. If you want that you can use [`ts-jest`](https://github.com/kulshekhar/ts-jest).
+
+#### Transforming images to their path
+
+Importing images is a way to include them in your browser bundle, but they are not valid JavaScript. One way of handling it in Jest is to replace the imported value with its filename.
+
+```js
+// fileTransformer.js
+const path = require('path');
+
+module.exports = {
+  process(src, filename, config, options) {
+    return 'module.exports = ' + JSON.stringify(path.basename(filename)) + ';';
+  },
+};
+```
+
+```js
+// jest.config.js
+
+module.exports = {
+  transform: {
+    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':
+      '<rootDir>/fileTransformer.js',
+  },
+};
+```

docs/Configuration.md

@@ -1263,8 +1263,7 @@ Examples of such compilers include:
 
 - [Babel](https://babeljs.io/)
 - [TypeScript](http://www.typescriptlang.org/)
-- [async-to-gen](http://github.com/leebyron/async-to-gen#jest)
-- To build your own please visit the [Custom Transformer](TutorialReact.md#custom-transformers) section
+- To build your own please visit the [Custom Transformer](CodeTransformation.md#writing-custom-transformers) section
 
 You can pass configuration to a transformer like `{filePattern: ['path-to-transformer', {options}]}` For example, to configure babel-jest for non-default behavior, `{"\\.js$": ['babel-jest', {rootMode: "upward"}]}`
 

docs/TutorialReact.md

@@ -304,7 +304,7 @@ The code for this example is available at [examples/enzyme](https://github.com/f
 
 ### Custom transformers
 
-If you need more advanced functionality, you can also build your own transformer. Instead of using babel-jest, here is an example of using babel:
+If you need more advanced functionality, you can also build your own transformer. Instead of using `babel-jest`, here is an example of using `@babel/core`:
 
 ```javascript
 // custom-transformer.js
@@ -320,7 +320,7 @@ module.exports = {
       presets: [jestPreset],
     });
 
-    return result ? result.code : src;
+    return result || src;
   },
 };
 ```
@@ -329,7 +329,7 @@ Don't forget to install the `@babel/core` and `babel-preset-jest` packages for t
 
 To make this work with Jest you need to update your Jest configuration with this: `"transform": {"\\.js$": "path/to/custom-transformer.js"}`.
 
-If you'd like to build a transformer with babel support, you can also use babel-jest to compose one and pass in your custom configuration options:
+If you'd like to build a transformer with babel support, you can also use `babel-jest` to compose one and pass in your custom configuration options:
 
 ```javascript
 const babelJest = require('babel-jest');
@@ -338,3 +338,5 @@ module.exports = babelJest.createTransformer({
   presets: ['my-custom-preset'],
 });
 ```
+
+See [dedicated docs](CodeTransformation.md#writing-custom-transformers) for more details.

e2e/coverage-transform-instrumented/preprocessor.js

@@ -18,16 +18,16 @@ const options = {
 
 module.exports = {
   canInstrument: true,
-  process(src, filename, config, transformOptions) {
+  process(src, filename, transformOptions) {
     options.filename = filename;
 
-    if (transformOptions && transformOptions.instrument) {
+    if (transformOptions.instrument) {
       options.auxiliaryCommentBefore = ' istanbul ignore next ';
       options.plugins = [
         [
           babelIstanbulPlugin,
           {
-            cwd: config.rootDir,
+            cwd: transformOptions.config.rootDir,
             exclude: [],
           },
         ],

e2e/snapshot-serializers/transformer.js

@@ -8,7 +8,7 @@
 'use strict';
 
 module.exports = {
-  process(src, filename, config, options) {
+  process(src, filename) {
     if (/bar.js$/.test(filename)) {
       return `${src};\nmodule.exports = createPlugin('bar');`;
     }

e2e/transform/custom-instrumenting-preprocessor/preprocessor.js

@@ -7,7 +7,7 @@
 
 module.exports = {
   canInstrument: true,
-  process(src, filename, config, options) {
+  process(src, filename, options) {
     src = `${src};\nglobal.__PREPROCESSED__ = true;`;
 
     if (options.instrument) {

e2e/transform/multiple-transformers/cssPreprocessor.js

@@ -6,7 +6,7 @@
  */
 
 module.exports = {
-  process(src, filename, config, options) {
+  process() {
     return `
       module.exports = {
         root: 'App-root',

e2e/transform/multiple-transformers/filePreprocessor.js

@@ -8,7 +8,7 @@
 const path = require('path');
 
 module.exports = {
-  process(src, filename, config, options) {
+  process(src, filename) {
     return `
       module.exports = '${path.basename(filename)}';
     `;

package.json

@@ -144,6 +144,7 @@
   },
   "resolutions": {
     "@types/jest/jest-diff": "^25.1.0",
-    "@types/jest/pretty-format": "^25.1.0"
+    "@types/jest/pretty-format": "^25.1.0",
+    "fbjs-scripts": "patch:fbjs-scripts@^1.1.0#./patches/fbjs-scripts.patch"
   }
 }

packages/babel-jest/src/__tests__/index.ts

@@ -35,11 +35,11 @@ beforeEach(() => {
 });
 
 test('Returns source string with inline maps when no transformOptions is passed', () => {
-  const result = babelJest.process(
-    sourceString,
-    'dummy_path.js',
-    makeProjectConfig(),
-  ) as any;
+  const result = babelJest.process(sourceString, 'dummy_path.js', {
+    config: makeProjectConfig(),
+    configString: JSON.stringify(makeProjectConfig()),
+    instrument: false,
+  }) as any;
   expect(typeof result).toBe('object');
   expect(result.code).toBeDefined();
   expect(result.map).toBeDefined();
@@ -86,7 +86,9 @@ describe('caller option correctly merges from defaults and options', () => {
       },
     ],
   ])('%j -> %j', (input, output) => {
-    babelJest.process(sourceString, 'dummy_path.js', makeProjectConfig(), {
+    babelJest.process(sourceString, 'dummy_path.js', {
+      config: makeProjectConfig(),
+      configString: JSON.stringify(makeProjectConfig()),
       instrument: false,
       ...input,
     });
@@ -107,7 +109,9 @@ describe('caller option correctly merges from defaults and options', () => {
 
 test('can pass null to createTransformer', () => {
   const transformer = babelJest.createTransformer(null);
-  transformer.process(sourceString, 'dummy_path.js', makeProjectConfig(), {
+  transformer.process(sourceString, 'dummy_path.js', {
+    config: makeProjectConfig(),
+    configString: JSON.stringify(makeProjectConfig()),
     instrument: false,
   });
 

packages/babel-jest/src/index.ts

@@ -9,8 +9,6 @@ import {createHash} from 'crypto';
 import * as path from 'path';
 import {
   PartialConfig,
-  PluginItem,
-  TransformCaller,
   TransformOptions,
   transformSync as babelTransform,
 } from '@babel/core';
@@ -28,23 +26,12 @@ const THIS_FILE = fs.readFileSync(__filename);
 const jestPresetPath = require.resolve('babel-preset-jest');
 const babelIstanbulPlugin = require.resolve('babel-plugin-istanbul');
 
-// Narrow down the types
-interface BabelJestTransformer extends Transformer {
-  canInstrument: true;
-}
-interface BabelJestTransformOptions extends TransformOptions {
-  caller: TransformCaller;
-  compact: false;
-  plugins: Array<PluginItem>;
-  presets: Array<PluginItem>;
-  sourceMaps: 'both';
-}
-
-const createTransformer = (
-  userOptions?: TransformOptions | null,
-): BabelJestTransformer => {
-  const inputOptions: TransformOptions = userOptions ?? {};
-  const options: BabelJestTransformOptions = {
+type CreateTransformer = Transformer<TransformOptions>['createTransformer'];
+
+const createTransformer: CreateTransformer = userOptions => {
+  const inputOptions = userOptions ?? {};
+
+  const options = {
     ...inputOptions,
     caller: {
       name: 'babel-jest',
@@ -58,7 +45,7 @@ const createTransformer = (
     plugins: inputOptions.plugins ?? [],
     presets: (inputOptions.presets ?? []).concat(jestPresetPath),
     sourceMaps: 'both',
-  };
+  } as const;
 
   function loadBabelConfig(
     cwd: Config.Path,
@@ -102,13 +89,13 @@ const createTransformer = (
 
   return {
     canInstrument: true,
-    getCacheKey(fileData, filename, configString, cacheKeyOptions) {
-      const {config, instrument, rootDir} = cacheKeyOptions;
+    getCacheKey(sourceText, sourcePath, transformOptions) {
+      const {config, configString, instrument} = transformOptions;
 
       const babelOptions = loadBabelConfig(
         config.cwd,
-        filename,
-        cacheKeyOptions,
+        sourcePath,
+        transformOptions,
       );
       const configPath = [
         babelOptions.config || '',
@@ -120,9 +107,9 @@ const createTransformer = (
         .update('\0', 'utf8')
         .update(JSON.stringify(babelOptions.options))
         .update('\0', 'utf8')
-        .update(fileData)
+        .update(sourceText)
         .update('\0', 'utf8')
-        .update(path.relative(rootDir, filename))
+        .update(path.relative(config.rootDir, sourcePath))
         .update('\0', 'utf8')
         .update(configString)
         .update('\0', 'utf8')
@@ -135,9 +122,13 @@ const createTransformer = (
         .update(process.env.BABEL_ENV || '')
         .digest('hex');
     },
-    process(src, filename, config, transformOptions) {
+    process(sourceText, sourcePath, transformOptions) {
       const babelOptions = {
-        ...loadBabelConfig(config.cwd, filename, transformOptions).options,
+        ...loadBabelConfig(
+          transformOptions.config.cwd,
+          sourcePath,
+          transformOptions,
+        ).options,
       };
 
       if (transformOptions?.instrument) {
@@ -148,14 +139,14 @@ const createTransformer = (
             babelIstanbulPlugin,
             {
               // files outside `cwd` will not be instrumented
-              cwd: config.rootDir,
+              cwd: transformOptions.config.rootDir,
               exclude: [],
             },
           ],
         ]);
       }
 
-      const transformResult = babelTransform(src, babelOptions);
+      const transformResult = babelTransform(sourceText, babelOptions);
 
       if (transformResult) {
         const {code, map} = transformResult;
@@ -164,14 +155,12 @@ const createTransformer = (
         }
       }
 
-      return src;
+      return sourceText;
     },
   };
 };
 
-const transformer: BabelJestTransformer & {
-  createTransformer: (options?: TransformOptions) => BabelJestTransformer;
-} = {
+const transformer: Transformer<TransformOptions> = {
   ...createTransformer(),
   // Assigned here so only the exported transformer has `createTransformer`,
   // instead of all created transformers by the function