@stencil/core 2.11.0 → 2.14.0

package/testing/jest/jest-config.d.ts

@@ -1,5 +1,16 @@
 import type * as d from '@stencil/core/internal';
 import type { Config } from '@jest/types';
+/**
+ * Builds the `argv` to be used when programmatically invoking the Jest CLI
+ * @param config the Stencil config to use while generating Jest CLI arguments
+ * @returns the arguments to pass to the Jest CLI, wrapped in an object
+ */
 export declare function buildJestArgv(config: d.Config): Config.Argv;
+/**
+ * Generate a Jest run configuration to be used as a part of the `argv` passed to the Jest CLI when it is invoked
+ * programmatically
+ * @param config the Stencil config to use while generating Jest CLI arguments
+ * @returns the Jest Config to attach to the `argv` argument
+ */
 export declare function buildJestConfig(config: d.Config): string;
 export declare function getProjectListFromCLIArgs(config: d.Config, argv: Config.Argv): Config.Path[];

package/testing/jest/jest-environment.d.ts

@@ -9,6 +9,7 @@ export declare function createJestPuppeteerEnvironment(): {
         newPuppeteerPage(): Promise<import("puppeteer").Page>;
         closeOpenPages(): Promise<void>;
         teardown(): Promise<void>;
+        getVmContext(): any;
     };
     [x: string]: any;
 };

package/testing/jest/jest-preprocessor.d.ts

@@ -1,11 +1,59 @@
+declare type Jest26CacheKeyOptions = {
+    instrument: boolean;
+    rootDir: string;
+};
+declare type Jest26Config = {
+    instrument: boolean;
+    rootDir: string;
+};
+declare type Jest27TransformOptions = {
+    config: Jest26Config;
+};
 export declare const jestPreprocessor: {
-    process(sourceText: string, filePath: string, jestConfig: {
-        rootDir: string;
-    }): string;
-    getCompilerOptions(rootDir: string): any;
-    getCacheKey(code: string, filePath: string, jestConfigStr: string, transformOptions: {
-        instrument: boolean;
-        rootDir: string;
-    }): string;
+    /**
+     * 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;
+    /**
+     * 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;
 };
+/**
+ * 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 declare function shouldTransform(filePath: string, sourceText: string): boolean;
+export {};

package/testing/jest/jest-runner.d.ts

@@ -1,5 +1,9 @@
 import type * as d from '@stencil/core/internal';
 export declare function runJest(config: d.Config, env: d.E2EProcessEnv): Promise<boolean>;
+/**
+ * Creates a Stencil test runner
+ * @returns the test runner
+ */
 export declare function createTestRunner(): any;
 export declare function includeTestFile(testPath: string, env: d.E2EProcessEnv): boolean;
 export declare function getEmulateConfigs(testing: d.TestingConfig, flags: d.ConfigFlags): d.EmulateConfig[];

package/testing/jest-preset.js

@@ -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, '..');

package/testing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/core/testing",
-  "version": "2.11.0",
+  "version": "2.14.0",
   "description": "Stencil testing suite.",
   "main": "./index.js",
   "types": "./index.d.ts",