@stencil/vitest 1.10.0 → 1.11.0

package/README.md

@@ -440,6 +440,101 @@ expect(clickSpy.firstEvent?.detail).toEqual({ buttonId: 'my-button' });
 expect(clickSpy.lastEvent?.detail).toEqual({ buttonId: 'my-button' });
 ```
 
+## Stencil Vitest Plugin
+
+The recommended testing approach in this package is to test against **pre-built dist outputs** — Stencil compiles your components once and tests run against those bundles. This is fast and reliable, but it does mean Vitest never sees individual component source files as discrete modules. As a result, `vi.mock()` cannot intercept imports made by your components, because the dependency is already bundled away before Vitest gets involved.
+
+`stencilVitestPlugin` solves this by hooking into Vite's transform pipeline. Every `.tsx` file containing Stencil decorators is compiled on-the-fly via `transpileSync` before Vitest imports it, using `componentExport: 'customelement'`. This means each component file becomes its own entry in Vitest's module graph — and its imports are independently resolvable and mockable.
+
+### Setup
+
+```typescript
+// vitest.config.ts
+import { defineVitestConfig } from '@stencil/vitest/config';
+import { stencilVitestPlugin } from '@stencil/vitest/plugin';
+
+export default defineVitestConfig({
+  stencilConfig: './stencil.config.ts',
+  test: {
+    projects: [
+      {
+        plugins: [stencilVitestPlugin()],
+        test: {
+          name: 'plugin',
+          environment: 'stencil',
+          include: ['src/**/*.plugin.spec.{ts,tsx}'],
+          // No dist setup file needed — each component source file registers
+          // itself via customElements.define() the moment it is imported.
+          // Optional environment options
+        },
+      },
+    ],
+  },
+});
+```
+
+### Mocking component dependencies
+
+With the plugin active, import the component source directly in your test. The plugin compiles it on-the-fly and the `customElements.define()` call at the end of the transformed output registers the element immediately.
+
+Given an example component:
+
+```tsx
+import { Component, Prop, h } from '@stencil/core';
+import { capitalize } from '../../utils/index.js';
+
+@Component( ... )
+export class MyLabel {
+  @Prop() value: string = '';
+
+  render() {
+    return <span class="label">{capitalize(this.value)}</span>;
+  }
+}
+```
+
+It can then be imported and tested with mocked dependencies:
+
+```tsx
+// my-label.plugin.spec.tsx
+import { describe, it, expect, vi } from 'vitest';
+import { render, h } from '@stencil/vitest';
+
+// vi.mock() is hoisted — the mock is in place before any imports resolve
+vi.mock('../utils/index.js', () => ({
+  capitalize: vi.fn((s: string) => `[mocked:${s}]`),
+}));
+
+// Importing the source file triggers the on-the-fly compile + define
+import './my-label.tsx';
+import { capitalize } from '../utils/index.js';
+
+it('renders using the mocked utility', async () => {
+  vi.mocked(capitalize).mockReturnValue('Intercepted');
+
+  const { root } = await render(<my-label value="hello" />);
+
+  expect(root.shadowRoot!.querySelector('span')?.textContent).toBe('Intercepted');
+  expect(capitalize).toHaveBeenCalledWith('hello');
+});
+```
+
+### Limitations
+
+#### Class inheritance
+
+In Stencil v4 `transpileSync` (used within the plugin) is a single-file compiler. When a component class `extends` a base class that lives in a separate file, `transpileSync` cannot follow the import to merge the parent's metadata and will throw an error.
+
+```tsx
+// ❌ Will fail — base class is in a separate file
+import { FormBase } from './form-base.js';
+
+@Component({ tag: 'my-input', shadow: true })
+export class MyInput extends FormBase { ... }
+```
+
+> This limitation is specific to v4. Stencil v5's compiler can resolve multi-file inheritance chains.
+
 ## Snapshots
 
 The package includes a custom snapshot serializer for Stencil components that properly handles shadow DOM:

package/dist/plugin.d.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from 'vitest/config';
+/**
+ * A Vite/Vitest plugin that transforms Stencil component source files (.tsx) on-the-fly,
+ * enabling module mocking and direct source imports during tests.
+ *
+ * The compiled output uses `componentExport: 'customelement'`, which appends a
+ * `customElements.define()` call at the end of the transformed file. The component
+ * registers itself the moment the module is imported — no dist loader or setup file
+ * required. Works with `@stencil/core` v4 and v5.
+ *
+ * @example
+ * ```ts
+ * // vitest.config.ts
+ * import { defineVitestConfig } from '@stencil/vitest/config';
+ * import { stencilVitestPlugin } from '@stencil/vitest/plugin';
+ *
+ * export default defineVitestConfig({
+ *   plugins: [stencilVitestPlugin()],
+ *   test: {
+ *     projects: [
+ *       {
+ *         test: {
+ *           name: 'stencil',
+ *           environment: 'stencil',
+ *           include: ['**\/*.spec.tsx'],
+ *           // No dist loader needed — import components from source directly
+ *         },
+ *       },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @returns a Vite plugin configuration object
+ */
+export declare function stencilVitestPlugin(): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAuD5C"}

package/dist/plugin.js

@@ -0,0 +1,82 @@
+/**
+ * A Vite/Vitest plugin that transforms Stencil component source files (.tsx) on-the-fly,
+ * enabling module mocking and direct source imports during tests.
+ *
+ * The compiled output uses `componentExport: 'customelement'`, which appends a
+ * `customElements.define()` call at the end of the transformed file. The component
+ * registers itself the moment the module is imported — no dist loader or setup file
+ * required. Works with `@stencil/core` v4 and v5.
+ *
+ * @example
+ * ```ts
+ * // vitest.config.ts
+ * import { defineVitestConfig } from '@stencil/vitest/config';
+ * import { stencilVitestPlugin } from '@stencil/vitest/plugin';
+ *
+ * export default defineVitestConfig({
+ *   plugins: [stencilVitestPlugin()],
+ *   test: {
+ *     projects: [
+ *       {
+ *         test: {
+ *           name: 'stencil',
+ *           environment: 'stencil',
+ *           include: ['**\/*.spec.tsx'],
+ *           // No dist loader needed — import components from source directly
+ *         },
+ *       },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @returns a Vite plugin configuration object
+ */
+export function stencilVitestPlugin() {
+    return {
+        name: 'stencil-vitest-transform',
+        enforce: 'pre',
+        async transform(code, id) {
+            // Only transform .tsx files
+            if (!id.endsWith('.tsx')) {
+                return null;
+            }
+            // Quick check for Stencil decorator patterns before paying the compiler cost
+            const hasStencilDecorator = code.includes('@Component') ||
+                code.includes('@Prop') ||
+                code.includes('@State') ||
+                code.includes('@Event') ||
+                code.includes('@Method') ||
+                code.includes('@Watch') ||
+                code.includes('@Listen');
+            if (!hasStencilDecorator) {
+                return null;
+            }
+            const { transpileSync } = await import('@stencil/core/compiler');
+            const result = transpileSync(code, {
+                file: id,
+                // 'customelement' appends a customElements.define() call so the component
+                // self-registers the moment this module is imported — no loader needed.
+                componentExport: 'customelement',
+                componentMetadata: 'compilerstatic',
+                currentDirectory: process.cwd(),
+                module: 'esm',
+                proxy: null,
+                sourceMap: false,
+                style: 'static',
+                styleImportData: 'queryparams',
+                target: 'es2022',
+                // Don't rewrite import paths — let Vite handle resolution via aliases
+                transformAliasedImportPaths: false,
+            });
+            const errors = result.diagnostics?.filter((d) => d.level === 'error') ?? [];
+            if (errors.length > 0) {
+                const messages = errors.map((d) => d.messageText).join('\n');
+                throw new Error(`[stencil-vitest-plugin] Transform error in ${id}:\n${messages}`);
+            }
+            return {
+                code: result.code,
+            };
+        },
+    };
+}

package/dist/testing/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/testing/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAyC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAExF,UAAU,aAAa;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AA+FD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCtG;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAY5F;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,GAAG,EACvE,QAAQ,EAAE,GAAG,GAAG,MAAM,EACtB,OAAO,GAAE,aAGR,GACA,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAqK7B"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/testing/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAyC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAExF,UAAU,aAAa;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AA+FD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCtG;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAY5F;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,GAAG,EACvE,QAAQ,EAAE,GAAG,GAAG,MAAM,EACtB,OAAO,GAAE,aAGR,GACA,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAyL7B"}

package/dist/testing/render.js

@@ -159,6 +159,17 @@ export async function render(template, options = {
     if (options.spyOn) {
         setRenderSpyConfig(options.spyOn);
     }
+    // Capture lifecycle errors (e.g. throws in componentWillLoad).
+    // Stencil's safeCall() catches all lifecycle hook errors and routes them to
+    // console.error instead of re-throwing.
+    let lifecycleError;
+    const origConsoleError = console.error;
+    console.error = (err, ...rest) => {
+        if (err instanceof Error && lifecycleError === undefined) {
+            lifecycleError = err;
+        }
+        origConsoleError(err, ...rest);
+    };
     if (typeof template === 'string') {
         // Handle string template - add as innerHTML
         container.innerHTML = template;
@@ -220,6 +231,12 @@ export async function render(template, options = {
         // Wait for Stencil's update cycle to complete
         await waitForChanges();
     }
+    // Restore console.error now that the lifecycle is done
+    console.error = origConsoleError;
+    // Re-throw any lifecycle error that Stencil's safeCall swallowed
+    if (lifecycleError !== undefined) {
+        throw lifecycleError;
+    }
     // Clear per-render spy config after component is ready
     if (options.spyOn) {
         setRenderSpyConfig(null);

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/stenciljs/vitest"
   },
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "First-class testing utilities for Stencil design systems with Vitest",
   "license": "MIT",
   "type": "module",
@@ -36,6 +36,10 @@
       "types": "./dist/setup/happy-dom-setup.d.ts",
       "import": "./dist/setup/happy-dom-setup.js"
     },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
     "./vitest": {
       "types": "./dist/environments/stencil.d.ts",
       "import": "./dist/environments/stencil.js"
@@ -100,7 +104,7 @@
   "dependencies": {
     "jiti": "^2.6.1",
     "local-pkg": "^1.1.2",
-    "vitest-environment-stencil": "1.10.0"
+    "vitest-environment-stencil": "1.11.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",