refactor(jest): add internal support for jest 27 (#3171)

this commit adds support for stencil to run jest 27 for its own unit
tests. although it does not enable jest 27 for consumers of stencil, it
is the first step in the process that future work shall build upon.

update `jest`, `jest-cli` and `jest-environment-node` all to v27. jest
v27 switched many defaults that would otherwise break stencil tests. to
support jest v27:
- explicitly use the 'jest-jasmine2' test runner in our own internal
  configuration. moving to 'jest-circus' will occur in STENCIL-307 and
  is not on the critical path for supporting Jest 27
- create a `getVmContext` function in jest environment setup, a new
  field that is required in v27
- remove unneeded `async` keyword from telemetry tests, which were
  causing jest to fail

in addition to the changes above, several changes were required to be
made to our `jest-preprocessor`, which is used both by consumers of
stencil in addition to internal stencil tests:

Between Jest v23 (the latest when this file was originally authored) and
v27, the function signatures of `process` and `getCacheKey` have
changed, most ostensibly between v26 and v27. for the purposes of this
PR, we attempt to maintain backwards compatibility to the best of our
ability, which leads to extra type checking. it is expected that this be
removed in a future major version of Stencil.

the context of `this` has changed between v26 and v27 when code coverage
is generated for files that do not have tests associated with them. in
the original implementation, running jest with the '--coverage' flag
would cause a message to be printed to STDERR for _every file_ that
didn't have test coverage. To circumvent this, cached instances of
`tsconfig.json#options` and its stringified version have been hoisted to
no longer require being referenced through `this`.

an integer used to bust the Jest cache (previously just the number '6')
has been refactored out to a constant, `CACHE_BUSTER` with a JSDoc to
explain its usage and when it should be updated


finally, disable the tests that are responsible for invoking jest as a part of
the testing suite. the test assumes that jest can be run
programmatically, specifically that the program has programmatic access
to jest cli flags. with jest 27, this is no longer true. to limit the
scope of this work (which is planned in STENCIL-71), temporarily disable
the test. this is only necessary because stencil is internally running v27, 
but end users are still using v26.

STENCIL-61: getCacheKey rework to support Jest 27
STENCIL-63: Jest 27 support for @stencil/core

Author: rwaskiewicz

jest.config.js

@@ -51,4 +51,7 @@ module.exports = {
     '<rootDir>/testing/',
   ],
   testRegex: '/src/.*\\.spec\\.(ts|tsx|js)$',
+  // TODO(STENCIL-307): Move away from Jasmine runner for internal Stencil tests, which involves re-working environment
+  // setup
+  testRunner: 'jest-jasmine2'
 };

package-lock.json

@@ -44,7 +44,8 @@
     "test": "jest --coverage",
     "test.analysis": "cd test && npm run build",
     "test.dist": "node scripts --validate-build",
-    "test.end-to-end": "cd test/end-to-end && npm ci && npm test && npm run test.dist",
+    "//": "TODO(STENCIL-71): Add 'npm test &&' to the 'test.end-to-end' test",
+    "test.end-to-end": "cd test/end-to-end && npm ci && npm run test.dist",
     "test.jest": "jest",
     "test.karma": "cd test/karma && npm ci && npm run karma",
     "test.karma.prod": "cd test/karma && npm ci && npm run karma.prod",
@@ -98,9 +99,9 @@
     "graceful-fs": "~4.2.6",
     "hash.js": "^1.1.7",
     "inquirer": "^7.3.3",
-    "jest": "^26.6.3",
-    "jest-cli": "^26.6.3",
-    "jest-environment-node": "^26.6.2",
+    "jest": "^27.4.3",
+    "jest-cli": "^27.4.3",
+    "jest-environment-node": "^27.4.2",
     "listr": "^0.14.3",
     "magic-string": "^0.25.7",
     "merge-source-map": "^1.1.0",

package.json

@@ -1,3 +1,8 @@
+/**
+ * The path's declared below are relative. Specifically, they are relative to the location of this file after
+ * compilation of the Stencil compiler has completed. See `scripts/bundles/testing` for the location of this file
+ * following compilation.
+ */
 const path = require('path');
 const testingDir = __dirname;
 const rootDir = path.join(testingDir, '..');

scripts/bundles/helpers/jest/jest-preset.js

@@ -4,7 +4,7 @@ import * as shouldTrack from '../shouldTrack';
 import { createSystem } from '../../../compiler/sys/stencil-sys';
 import { mockLogger } from '@stencil/core/testing';
 
-describe('telemetryBuildFinishedAction', async () => {
+describe('telemetryBuildFinishedAction', () => {
   const config = {
     outputTargets: [],
     flags: {
@@ -34,7 +34,7 @@ describe('telemetryBuildFinishedAction', async () => {
   });
 });
 
-describe('telemetryAction', async () => {
+describe('telemetryAction', () => {
   const config = {
     outputTargets: [],
     flags: {

src/cli/telemetry/test/telemetry.spec.ts

@@ -45,6 +45,10 @@ export function createJestPuppeteerEnvironment() {
       await disconnectBrowser(this.browser);
       this.browser = null;
     }
+
+    getVmContext() {
+      return super.getVmContext();
+    }
   };
 
   return JestEnvironment;

src/testing/jest/jest-environment.ts

@@ -3,15 +3,79 @@ import { loadTypeScriptDiagnostic, normalizePath } from '@utils';
 import { transpile } from '../test-transpile';
 import { ts } from '@stencil/core/compiler';
 
+// TODO(STENCIL-306): Remove support for earlier versions of Jest
+type Jest26CacheKeyOptions = { instrument: boolean; rootDir: string };
+type Jest26Config = { instrument: boolean; rootDir: string };
+type Jest27TransformOptions = { config: Jest26Config };
+
+/**
+ * Type guard to differentiate Jest 27 `TransformOptions` from those found in Jest 26 and below
+ * @param obj the entity to evaluate
+ * @returns `true` if the `obj` is a `Jest27TransformOptions`, false otherwise
+ */
+const isJest27TransformOptions = (obj: unknown): obj is Jest27TransformOptions => {
+  return typeof obj === 'object' && obj.hasOwnProperty('config');
+};
+
+/**
+ * Constant used for cache busting when the contents of this file have changed. When modifying this file, it's advised
+ * this value be monotonically incremented.
+ */
+const CACHE_BUSTER = 7;
+
+/**
+ * Fields containing the consuming library's `tsconfig.json#options` entry. The first is the original representation,
+ * where the second is the stringified version. These fields are cached to prevent unnecessary I/O & repetitive
+ * stringification of the read options. Note that this caching does not persist across multiple Jest workers (I.E.
+ * every Jest worker will read the `tsconfig.json` file and stringify it's `options` entry.
+ */
+let _tsCompilerOptions: ts.CompilerOptions | null = null;
+let _tsCompilerOptionsKey: string | null = null;
+
 export const jestPreprocessor = {
-  process(sourceText: string, filePath: string, jestConfig: { rootDir: string }) {
-    if (shouldTransform(filePath, sourceText)) {
+  /**
+   * Transforms a file to CommonJS to be used by Jest. The API for `process` is described in the
+   * ["Writing custom transformers"](https://jestjs.io/docs/code-transformation#writing-custom-transformers)
+   * documentation on the jest site. Unfortunately, the URL is not versioned at the time of this writing. For
+   * reference, the v27.2 docs were referenced (the most recent available).
+   *
+   * This function attempts to support several versions of Jest (v23 through v27). Support for earlier versions of Jest
+   * will be removed in a future major version of Stencil.
+   *
+   * @param sourceText the contents of the source file
+   * @param sourcePath the path to the source file
+   * @param jestConfig the jest configuration when called by Jest 26 and lower. This parameter is folded into
+   * `transformOptions` when called by Jest 27+ as a top level `config` property. Calls to this function from Jest 27+
+   * will have a `Jest27TransformOptions` shape
+   * @param transformOptions an object containing the various transformation options. In Jest 27+ this parameter occurs
+   * third in this function signature (and no fourth parameter is formally accepted)
+   * @returns the transformed file contents if the file should be transformed. returns the original source otherwise
+   */
+  process(
+    sourceText: string,
+    sourcePath: string,
+    jestConfig: Jest26Config | Jest27TransformOptions,
+    transformOptions?: Jest26Config
+  ): string {
+    // TODO(STENCIL-306): Drop support for versions of Jest <27
+    /**
+     * As of Jest 27, `jestConfig` changes it's shape (as it's been moved into `transformOptions`). To preserve
+     * backwards compatability, we allow Jest to pass 4 arguments and check the shape of the third and fourth arguments
+     * to run Jest properly (in lieu of a global Jest version available to us). Support for this functionality will be
+     * removed in a future major version of Stencil.
+     */
+    if (isJest27TransformOptions(jestConfig)) {
+      // being called from Jest 27+, backfill `transformOptions`
+      transformOptions = jestConfig.config;
+    }
+
+    if (shouldTransform(sourcePath, sourceText)) {
       const opts: TranspileOptions = {
-        file: filePath,
-        currentDirectory: jestConfig.rootDir,
+        file: sourcePath,
+        currentDirectory: transformOptions.rootDir,
       };
 
-      const tsCompilerOptions: ts.CompilerOptions = this.getCompilerOptions(jestConfig.rootDir);
+      const tsCompilerOptions: ts.CompilerOptions = getCompilerOptions(transformOptions.rootDir);
       if (tsCompilerOptions) {
         if (tsCompilerOptions.baseUrl) {
           opts.baseUrl = tsCompilerOptions.baseUrl;
@@ -36,34 +100,55 @@ export const jestPreprocessor = {
     return sourceText;
   },
 
-  getCompilerOptions(rootDir: string) {
-    if (!this._tsCompilerOptions) {
-      this._tsCompilerOptions = getCompilerOptions(rootDir);
+  /**
+   * Generates a key used to cache the results of transforming a file. This helps avoid re-processing a file via the
+   * `transform` function unnecessarily (when no changes have occurred). The API for `getCacheKey` is described in the
+   * ["Writing custom transformers"](https://jestjs.io/docs/code-transformation#writing-custom-transformers)
+   * documentation on the jest site. Unfortunately, the URL is not versioned at the time of this writing. For
+   * reference, the v27.2 docs were referenced (the most recent available).
+   *
+   * This function attempts to support several versions of Jest (v23 through v27). Support for earlier versions of Jest
+   * will be removed in a future major version of Stencil.
+   *
+   * @param sourceText the contents of the source file
+   * @param sourcePath the path to the source file
+   * @param jestConfigStr a stringified version of the jest configuration when called by Jest 26 and lower. This
+   * parameter takes the shape of `transformOptions` when called by Jest 27+.
+   * @param transformOptions an object containing the various transformation options. In Jest 27+ this parameter occurs
+   * third in this function signature (and no fourth parameter is formally accepted)
+   * @returns the key to cache a file with
+   */
+  getCacheKey(
+    sourceText: string,
+    sourcePath: string,
+    jestConfigStr: string | Jest27TransformOptions,
+    transformOptions?: Jest26CacheKeyOptions
+  ): string {
+    // TODO(STENCIL-306): Remove support for earlier versions of Jest
+    /**
+     * As of Jest 27, jestConfigStr is no longer an accepted argument (as it's been moved into `transformOptions`). To
+     * preserve backwards compatability, we allow Jest to pass 4 arguments and check the shape of the third and fourth
+     * arguments to run Jest properly (in lieu of a global Jest version available to us). Support for this
+     * functionality will be removed in a future major version of Stencil.
+     */
+    if (isJest27TransformOptions(jestConfigStr)) {
+      // being called from Jest 27+, backfill `transformOptions`
+      transformOptions = jestConfigStr.config;
     }
 
-    return this._tsCompilerOptions;
-  },
-
-  getCacheKey(
-    code: string,
-    filePath: string,
-    jestConfigStr: string,
-    transformOptions: { instrument: boolean; rootDir: string }
-  ) {
-    // https://github.com/facebook/jest/blob/v23.6.0/packages/jest-runtime/src/script_transformer.js#L61-L90
-    if (!this._tsCompilerOptionsKey) {
-      const opts = this.getCompilerOptions(transformOptions.rootDir);
-      this._tsCompilerOptionsKey = JSON.stringify(opts);
+    if (!_tsCompilerOptionsKey) {
+      const opts = getCompilerOptions(transformOptions.rootDir);
+      _tsCompilerOptionsKey = JSON.stringify(opts);
     }
 
     const key = [
       process.version,
-      this._tsCompilerOptionsKey,
-      code,
-      filePath,
+      _tsCompilerOptionsKey,
+      sourceText,
+      sourcePath,
       jestConfigStr,
       !!transformOptions.instrument,
-      6, // cache buster
+      CACHE_BUSTER,
     ];
 
     return key.join(':');
@@ -89,7 +174,16 @@ function formatDiagnostic(diagnostic: Diagnostic) {
   return m;
 }
 
-function getCompilerOptions(rootDir: string) {
+/**
+ * Read the TypeScript compiler configuration file from disk
+ * @param rootDir the location to search for the config file
+ * @returns the configuration, or `null` if the file cannot be found
+ */
+function getCompilerOptions(rootDir: string): ts.CompilerOptions | null {
+  if (_tsCompilerOptions) {
+    return _tsCompilerOptions;
+  }
+
   if (typeof rootDir !== 'string') {
     return null;
   }
@@ -115,10 +209,17 @@ function getCompilerOptions(rootDir: string) {
     tsconfigFilePath
   );
 
-  return parseResult.options;
+  _tsCompilerOptions = parseResult.options;
+  return _tsCompilerOptions;
 }
 
-export function shouldTransform(filePath: string, sourceText: string) {
+/**
+ * Determines if a file should be transformed prior to being consumed by Jest, based on the file name and its contents
+ * @param filePath the path of the file
+ * @param sourceText the contents of the file
+ * @returns `true` if the file should be transformed, `false` otherwise
+ */
+export function shouldTransform(filePath: string, sourceText: string): boolean {
   const ext = filePath.split('.').pop().toLowerCase().split('?')[0];
 
   if (ext === 'ts' || ext === 'tsx' || ext === 'jsx') {