@stencil/vitest 1.11.2 → 1.11.4

package/README.md

@@ -2,6 +2,38 @@
 
 First-class testing utilities for Stencil components, powered by Vitest.
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+  - [1. Install](#1-install)
+  - [2. Create vitest.config.ts](#2-create-vitestconfigts)
+  - [3. Load your components](#3-load-your-components)
+  - [4. Write Tests](#4-write-tests)
+  - [5. Run tests](#5-run-tests)
+- [API](#api)
+  - [Rendering](#rendering)
+  - [Available matchers](#available-matchers)
+  - [Spying and Mocking](#spying-and-mocking)
+  - [Event Testing](#event-testing)
+- [Stencil Vitest Plugin (Experimental)](#stencil-vitest-plugin)
+  - [Setup](#setup)
+  - [Mocking component dependencies](#mocking-component-dependencies)
+  - [Limitations](#limitations)
+- [Snapshots](#snapshots)
+- [Screenshot Testing](#screenshot-testing)
+- [Utils](#utils)
+  - [serializeHtml](#serializehtmlelement-options)
+  - [prettifyHtml](#prettifyhtmlhtml)
+  - [waitForStable](#waitforstableelementorselector-timeout)
+  - [waitForExist](#waitforexistselector-timeout)
+- [CLI](#cli)
+  - [Usage](#usage)
+  - [Flags](#flags)
+  - [Global Variables](#global-variables)
+- [Limitations / Gotchas](#limitations--gotchas)
+- [License](#license)
+- [Contributing](#contributing)
+
 ## Quick Start
 
 ### 1. Install
@@ -442,9 +474,12 @@ 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.
+All examples so far have mentioned setting up tests against **pre-built dist outputs**; Stencil compiles your components once and tests run against those bundles. Whilst this method is fast and reliable, it does mean Vitest never sees individual component source files as discrete modules and so does have 2 key limitations:
+
+1. `vi.mock()` cannot intercept imports made by your components, because the dependency is already bundled away before Vitest gets involved.
+2. Coverage reports will not work out-of-the-box without additional configuration (`sourceMap: true` / [3rd party tools](https://github.com/cenfun/vitest-monocart-coverage)) and even then, may not be accurate.
 
-`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.
+The experimental `stencilVitestPlugin` solves this by hooking into Vite's transform pipeline: Stencil files are compiled on-the-fly before Vitest imports them; each component file becomes its own entry in Vitest's module graph — and its imports are independently resolvable and mockable.
 
 ### Setup
 
@@ -461,11 +496,11 @@ export default defineVitestConfig({
         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
+
+          environment: 'stencil',
+          // ^^ you can use the plugin with any setup - even browser tests!
         },
       },
     ],
@@ -523,7 +558,7 @@ it('renders using the mocked utility', async () => {
 
 #### 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.
+In Stencil v4 `transpile()` (used within the plugin) is a single-file compiler. When a component class `extends` a base class that lives in a separate file, `transpile()` 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
@@ -533,7 +568,7 @@ import { FormBase } from './form-base.js';
 export class MyInput extends FormBase { ... }
 ```
 
-> This limitation is specific to v4. Stencil v5's compiler can resolve multi-file inheritance chains.
+> This limitation is specific to v4. Stencil v5's `transpile()` can resolve multi-file inheritance chains.
 
 ## Snapshots
 
@@ -646,17 +681,6 @@ const element = await waitForExist('#dynamic-content', 10000);
 
 The `stencil-test` CLI wraps both Stencil builds with Vitest testing.
 
-### Add to package.json
-
-```json
-{
-  "scripts": {
-    "test": "stencil-test",
-    "test:watch": "stencil-test --watch"
-  }
-}
-```
-
 ### Usage
 
 ```bash
@@ -682,12 +706,14 @@ stencil-test button.spec.ts
 stencil-test --project browser
 ```
 
-### CLI Options
+### Flags
+
+The `stencil-test` CLI supports most of Stencil's CLI flags and all of Vitest CLI flags
 
-The `stencil-test` CLI supports most of Stencil's CLI options and all of Vitest CLI options
+- For full Stencil CLI flags, see [Stencil CLI docs](https://stenciljs.com/docs/cli).
+- For full Vitest CLI flags, see [Vitest CLI docs](https://vitest.dev/guide/cli.html).
 
-- For full Stencil CLI options, see [Stencil CLI docs](https://stenciljs.com/docs/cli).
-- For full Vitest CLI options, see [Vitest CLI docs](https://vitest.dev/guide/cli.html).
+Note: unlike a normal `stencil build` `stencil-vitest` runs in development mode by default for faster builds. Use `--prod` to test against a production build.
 
 ### Global Variables
 
@@ -721,6 +747,16 @@ Add to your `tsconfig.json` for type definitions:
 }
 ```
 
+## Limitations / Gotchas
+
+### `vi.mock()` doesn't work?
+
+Modules can only be mocked if they are imported in a way that Vitest can intercept. If your components are importing dependencies that you want to mock, you must use the `stencilVitestPlugin` to compile components on-the-fly and allow Vitest to mock their imports. See the [Stencil Vitest Plugin section](#stencil-vitest-plugin) for details.
+
+### Coverage reports are empty or inaccurate?
+
+When testing against pre-built dist outputs, source maps (`sourceMap: true` in `stencil.config.ts`) and [3rd party tools](https://github.com/cenfun/vitest-monocart-coverage) are required for coverage reports. Alternatively, consider using the `stencilVitestPlugin` which compiles components on-the-fly and provides better coverage support.
+
 ## License
 
 MIT

package/dist/environments/stencil.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stencil.d.ts","sourceRoot":"","sources":["../../src/environments/stencil.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBvD,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;CACrD;AAQD;;;;;;;;;;;;;;;;GAgBG;wBACa,WAAW;AAA3B,wBAwEE"}
+{"version":3,"file":"stencil.d.ts","sourceRoot":"","sources":["../../src/environments/stencil.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiBvD,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;CACrD;AAQD;;;;;;;;;;;;;;;;GAgBG;wBACa,WAAW;AAA3B,wBA6FE"}

package/dist/environments/stencil.js

@@ -77,6 +77,26 @@ export default {
         if (originals.has('Event')) {
             global.Event = originals.get('Event');
         }
+        // Create HTMLElement wrapper that captures ownerDocument
+        // In Stencil 4.43+, win.HTMLElement returns MockHTMLElement directly which expects
+        // ownerDocument as the first constructor arg. But Stencil-compiled components call
+        // super() with no args (standard browser behavior). This wrapper bridges the gap.
+        const MockHTMLElementBase = global.HTMLElement;
+        const doc = win.document;
+        global.HTMLElement = class extends MockHTMLElementBase {
+            constructor() {
+                super(doc, '');
+                const observedAttributes = this.constructor.observedAttributes;
+                if (Array.isArray(observedAttributes) && typeof this.attributeChangedCallback === 'function') {
+                    observedAttributes.forEach((attrName) => {
+                        const attrValue = this.getAttribute(attrName);
+                        if (attrValue != null) {
+                            this.attributeChangedCallback(attrName, null, attrValue);
+                        }
+                    });
+                }
+            }
+        };
         // Remove undefined properties that shadow native globals
         keys.forEach((key) => {
             if (global[key] === undefined && originals.has(key)) {

package/dist/plugin.d.ts

@@ -30,7 +30,7 @@ import type { Plugin } from 'vitest/config';
  *   },
  * });
  * ```
- *
+ * @param opts Optional configuration for the plugin
  * @returns a Vite plugin configuration object
  */
 export declare function stencilVitestPlugin(): Plugin;

package/dist/plugin.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAyF5C"}

package/dist/plugin.js

@@ -1,3 +1,6 @@
+import { transpile } from '@stencil/core/compiler';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 /**
  * A Vite/Vitest plugin that transforms Stencil component source files (.tsx) on-the-fly,
  * enabling module mocking and direct source imports during tests.
@@ -29,14 +32,43 @@
  *   },
  * });
  * ```
- *
+ * @param opts Optional configuration for the plugin
  * @returns a Vite plugin configuration object
  */
 export function stencilVitestPlugin() {
     return {
         name: 'stencil-vitest-transform',
         enforce: 'pre',
+        resolveId(id, importer) {
+            if (id.includes('.css') && id.includes('tag=')) {
+                const [relPath] = id.split('?');
+                const query = id.slice(id.indexOf('?'));
+                const resolved = resolve(dirname(importer), relPath);
+                // Remove .css from virtual ID to prevent Vite's CSS plugin from hijacking the output
+                return '\0stencil-style:' + resolved.replace(/\.css$/, '') + query;
+            }
+            return null;
+        },
+        load(id) {
+            if (id.startsWith('\0stencil-style:')) {
+                // Add .css back to get the real file path
+                const realPath = id.slice('\0stencil-style:'.length).split('?')[0] + '.css';
+                return readFileSync(realPath, 'utf-8');
+            }
+            return null;
+        },
         async transform(code, id) {
+            if (id.startsWith('\0stencil-style:')) {
+                // Reconstruct the original .css path for Stencil's transpiler (it uses extension to detect file type)
+                const pathWithoutPrefix = id.slice('\0stencil-style:'.length);
+                const [basePath, query] = pathWithoutPrefix.split('?');
+                const originalPath = basePath + '.css' + (query ? '?' + query : '');
+                const result = await transpile(code, { file: originalPath });
+                return {
+                    code: result.code,
+                    map: null,
+                };
+            }
             // Only transform .tsx files
             if (!id.endsWith('.tsx')) {
                 return null;
@@ -52,31 +84,35 @@ export function stencilVitestPlugin() {
             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}`);
+            try {
+                const result = await transpile(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',
+                    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,
+                };
+            }
+            catch (err) {
+                console.error(`[stencil-vitest-plugin] Failed to transform ${id}:`, err);
+                throw err;
             }
-            return {
-                code: result.code,
-            };
         },
     };
 }

package/dist/setup/mock-doc-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-doc-setup.d.ts","sourceRoot":"","sources":["../../src/setup/mock-doc-setup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAc,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,QAmD7C;AAOD,QAAA,IAAI,GAAG,EAAE,GAAG,CAAC;AACb,QAAA,IAAI,GAAG,EAAE,GAAG,CAAC;AA4Bb,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"mock-doc-setup.d.ts","sourceRoot":"","sources":["../../src/setup/mock-doc-setup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAc,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,QAmD7C;AAOD,QAAA,IAAI,GAAG,EAAE,GAAG,CAAC;AACb,QAAA,IAAI,GAAG,EAAE,GAAG,CAAC;AA6Bb,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC"}

package/dist/setup/mock-doc-setup.js

@@ -80,6 +80,7 @@ else {
     globalThis.document = doc;
     globalThis.HTMLElement = win.HTMLElement;
     globalThis.CustomEvent = win.CustomEvent;
+    globalThis.Event = win.Event;
     globalThis.Element = win.Element;
     globalThis.Node = win.Node;
     globalThis.DocumentFragment = win.DocumentFragment;

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/stenciljs/vitest"
   },
-  "version": "1.11.2",
+  "version": "1.11.4",
   "description": "First-class testing utilities for Stencil design systems with Vitest",
   "license": "MIT",
   "type": "module",
@@ -104,7 +104,7 @@
   "dependencies": {
     "jiti": "^2.6.1",
     "local-pkg": "^1.1.2",
-    "vitest-environment-stencil": "1.11.2"
+    "vitest-environment-stencil": "1.11.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",