feat(testing): deprecate all integrated testing options (#6642)

johnjenkins · web-flow · commit 02f91b3b5946 · 2026-03-17T22:36:13.000Z
diff --git a/src/cli/config-flags.ts b/src/cli/config-flags.ts
@@ -13,6 +13,7 @@ export const BOOLEAN_CLI_FLAGS = [
   'dev',
   'devtools',
   'docs',
+  // @deprecated - integrated testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
   'e2e',
   'es5',
   'esm',
@@ -24,16 +25,21 @@ export const BOOLEAN_CLI_FLAGS = [
   'prod',
   'profile',
   'serviceWorker',
+  // @deprecated - screenshot testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
   'screenshot',
   'serve',
   'skipNodeCheck',
+  // @deprecated - integrated testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
   'spec',
   'ssr',
+  // @deprecated - screenshot testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
   'updateScreenshot',
   'verbose',
   'version',
   'watch',
 
+  // @deprecated - all JEST CLI options below are only used by integrated testing, which will be removed in Stencil v5.
+  // See https://github.com/stenciljs/core/issues/6584.
   // JEST CLI OPTIONS
   'all',
   'automock',
@@ -88,6 +94,8 @@ export const BOOLEAN_CLI_FLAGS = [
  */
 export const NUMBER_CLI_FLAGS = [
   'port',
+  // @deprecated - all JEST CLI args below are only used by integrated testing, which will be removed in Stencil v5.
+  // See https://github.com/stenciljs/core/issues/6584.
   // JEST CLI ARGS
   'maxConcurrency',
   'testTimeout',
@@ -103,8 +111,11 @@ export const STRING_CLI_FLAGS = [
   'docsJson',
   'emulate',
   'root',
+  // @deprecated - screenshot testing will be removed in Stencil v5. See https://github.com/stenciljs/core/issues/6584.
   'screenshotConnector',
 
+  // @deprecated - all JEST CLI args below are only used by integrated testing, which will be removed in Stencil v5.
+  // See https://github.com/stenciljs/core/issues/6584.
   // JEST CLI ARGS
   'cacheDirectory',
   'changedSince',
@@ -138,6 +149,8 @@ export const STRING_CLI_FLAGS = [
   'transform',
 ] as const;
 
+// @deprecated - all entries below are JEST CLI args only used by integrated testing, which will be removed in Stencil v5.
+// See https://github.com/stenciljs/core/issues/6584.
 export const STRING_ARRAY_CLI_FLAGS = [
   'collectCoverageOnlyFrom',
   'coveragePathIgnorePatterns',
diff --git a/src/cli/task-test.ts b/src/cli/task-test.ts
@@ -6,6 +6,15 @@ import type { TestingRunOptions, ValidatedConfig } from '../declarations';
  * @returns a void promise
  */
 export const taskTest = async (config: ValidatedConfig): Promise<void> => {
+  config.logger.warn(
+    config.logger.yellow(
+      `[DEPRECATION] Stencil's integrated testing (the 'test' task, --spec and --e2e flags) is deprecated and will be removed in Stencil v5. ` +
+        `Migrate spec tests to @stencil/vitest (https://github.com/stenciljs/vitest) and ` +
+        `e2e / browser tests to either @stencil/vitest (https://github.com/stenciljs/vitest) or ` +
+        `@stencil/playwright (https://github.com/stenciljs/playwright). ` +
+        `See https://github.com/stenciljs/core/issues/6584 for full details.`,
+    ),
+  );
   config.buildDocs = false;
   const testingRunOpts: TestingRunOptions = {
     e2e: !!config.flags.e2e,
diff --git a/src/declarations/stencil-public-compiler.ts b/src/declarations/stencil-public-compiler.ts
@@ -285,6 +285,15 @@ export interface StencilConfig {
 
   globalScript?: string;
   srcIndexHtml?: string;
+  /**
+   * Configuration for Stencil's integrated testing (Jest + Puppeteer).
+   *
+   * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+   * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+   * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+   * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+   * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
+   */
   testing?: TestingConfig;
   maxConcurrentWorkers?: number;
   preamble?: string;
@@ -1899,6 +1908,13 @@ export interface RollupOutputOptions {
   globals?: { [name: string]: string } | ((name: string) => string);
 }
 
+/**
+ * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+ * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+ * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
+ */
 export interface Testing {
   run(opts: TestingRunOptions): Promise<boolean>;
   destroy(): Promise<void>;
@@ -1909,6 +1925,12 @@ export declare type TransformerConfig = [string, Record<string, unknown>];
 
 /**
  * Options for initiating a run of Stencil tests (spec and/or end-to-end)
+ *
+ * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+ * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+ * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
  */
 export interface TestingRunOptions {
   /**
@@ -1929,6 +1951,13 @@ export interface TestingRunOptions {
   updateScreenshot?: boolean;
 }
 
+/**
+ * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+ * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+ * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
+ */
 export interface JestConfig {
   /**
    * This option tells Jest that all imported modules in your tests should be mocked automatically.
@@ -2061,6 +2090,15 @@ export interface JestConfig {
   watchPathIgnorePatterns?: any[];
 }
 
+/**
+ * Configuration for Stencil's integrated testing (Jest + Puppeteer).
+ *
+ * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+ * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+ * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
+ */
 export interface TestingConfig extends JestConfig {
   /**
    * The `allowableMismatchedPixels` value is used to determine an acceptable
@@ -2168,6 +2206,13 @@ export interface TestingConfig extends JestConfig {
   waitBeforeScreenshot?: number;
 }
 
+/**
+ * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+ * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+ * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
+ */
 export interface EmulateConfig {
   /**
    * Predefined device descriptor name, such as "iPhone X" or "Nexus 10".
@@ -2183,6 +2228,13 @@ export interface EmulateConfig {
   viewport?: EmulateViewport;
 }
 
+/**
+ * @deprecated Integrated testing support will be removed in Stencil v5. Migrate spec tests to
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) and e2e / browser tests to either
+ * [`@stencil/vitest`](https://github.com/stenciljs/vitest) or
+ * [`@stencil/playwright`](https://github.com/stenciljs/playwright).
+ * See https://github.com/stenciljs/core/issues/6584 for full discussion and migration guidance.
+ */
 export interface EmulateViewport {
   /**
    * Page width in pixels.
