@stencil/vitest 0.0.1-dev.20260109124515.90fb962

package/README.md

@@ -0,0 +1,296 @@
+# @stencil/vitest
+
+First-class testing utilities for Stencil components, powered by Vitest.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm i --save-dev @stencil/vitest vitest
+```
+
+For browser testing, also install:
+
+```bash
+npm i -D @vitest/browser-playwright
+# or
+npm i -D @vitest/browser-webdriverio
+```
+
+### 2. Create `vitest.config.ts`
+
+```typescript
+import { defineVitestConfig } from '@stencil/vitest/config';
+import { playwright } from '@vitest/browser-playwright';
+
+export default defineVitestConfig({
+  stencilConfig: './stencil.config.ts',
+  test: {
+    projects: [
+      // Unit tests - node environment for functions / logic
+      {
+        test: {
+          name: 'unit',
+          include: ['src/**/*.unit.{ts,tsx}'],
+          environment: 'node',
+        },
+      },
+      // Spec tests - via a node DOM of your choice
+      {
+        test: {
+          name: 'spec',
+          include: ['src/**/*.spec.{ts,tsx}'],
+          environment: 'stencil',
+          setupFiles: ['./vitest-setup.ts'],
+
+          // Optional environment options
+
+          // environmentOptions: {
+          //   stencil: {
+          //     domEnvironment: 'happy-dom' | 'jsdom' | 'mock-doc' (default)
+          //                      ^^ Make sure to install relevant packages
+          //   },
+          // },
+        },
+      },
+      // Browser tests
+      {
+        test: {
+          name: 'browser',
+          include: ['src/**/*.test.{ts,tsx}'],
+          setupFiles: ['./vitest-setup.ts'],
+          browser: {
+            enabled: true,
+            provider: playwright(),
+            headless: true,
+            instances: [{ browser: 'chromium' }],
+          },
+        },
+      },
+    ],
+  },
+});
+```
+
+[refer Vitest documentation for all configuration options](https://vitest.dev/config/)
+
+### 3. Load your components
+
+```typescript
+// vitest-setup.ts
+
+// Load Stencil components.
+// Adjust according to your build output of choice *
+await import('./dist/test-components/test-components.esm.js');
+
+export {};
+// * Bear in mind, you may need `buildDist: true` (in your stencil.config)
+// or `--prod` to use an output other than the browser lazy-loader
+```
+
+### 4. Write Tests
+
+```tsx
+// src/components/my-button/my-button.spec.tsx
+
+import { describe, it, expect } from 'vitest';
+import { render, h } from '@stencil/vitest';
+
+describe('my-button', () => {
+  it('renders with text', async () => {
+    const { root, waitForChanges } = await render(<my-button label="Click me" />);
+    root.click();
+    await waitForChanges();
+    expect(root).toEqualHtml(`
+      <my-button class="hydrated">
+        <mock:shadow-root>
+          <button class="button button--secondary button--small" type="button">
+            <slot></slot>
+          </button>
+        </mock:shadow-root>
+        Small
+      </my-button>
+    `);
+  });
+});
+```
+
+### 5. Run tests
+
+```json
+// package.json
+{
+  "scripts": {
+    "test": "stencil-test",
+    "test:watch": "stencil-test --watch",
+    "test:e2e": "stencil-test --project browser",
+    "test:spec": "stencil-test --project spec"
+  }
+}
+```
+
+## API
+
+### Rendering
+
+#### `render(VNode)`
+
+Render a component for testing.
+
+```tsx
+import { render, h } from '@stencil/vitest';
+
+const { root, waitForChanges, setProps, unmount } = await render(<my-component name="World" />);
+
+// Access the element
+expect(root.textContent).toContain('World');
+
+// Update props
+root.name = 'Stencil';
+await waitForChanges();
+// or
+await setProps({ name: 'Stencil' });
+
+// Unmount component
+unmount();
+```
+
+### Available matchers:
+
+```typescript
+// DOM assertions
+expect(element).toHaveClass('active');
+expect(element).toHaveClasses(['active', 'primary']);
+expect(element).toMatchClasses(['active']); // Partial match
+expect(element).toHaveAttribute('aria-label', 'Close');
+expect(element).toEqualAttribute('type', 'button');
+expect(element).toEqualAttributes({ type: 'button', disabled: true });
+expect(element).toHaveProperty('value', 'test');
+expect(element).toHaveTextContent('Hello World');
+expect(element).toEqualText('Exact text match');
+expect(element).toBeVisible();
+
+// Shadow DOM
+expect(element).toHaveShadowRoot();
+expect(element).toEqualHtml('<div>Expected HTML</div>');
+expect(element).toEqualLightHtml('<div>Light DOM only</div>');
+```
+
+### Event Testing
+
+Test custom events emitted by your components:
+
+```tsx
+const { root, spyOnEvent, waitForChanges } = await render(<my-button />);
+
+// Spy on events
+const clickSpy = spyOnEvent('buttonClick');
+const changeSpy = spyOnEvent('valueChange');
+
+// Trigger events
+root.click();
+await waitForChanges();
+
+// Assert events were emitted
+expect(clickSpy).toHaveReceivedEvent();
+expect(clickSpy).toHaveReceivedEventTimes(1);
+expect(clickSpy).toHaveReceivedEventDetail({ buttonId: 'my-button' });
+
+// Access event data
+expect(clickSpy.events).toHaveLength(1);
+expect(clickSpy.firstEvent?.detail).toEqual({ buttonId: 'my-button' });
+expect(clickSpy.lastEvent?.detail).toEqual({ buttonId: 'my-button' });
+```
+
+## Snapshots
+
+The package includes a custom snapshot serializer for Stencil components that properly handles shadow DOM:
+
+```tsx
+import { render, h } from '@stencil/vitest';
+...
+const { root } = await render(<my-component />);
+expect(root).toMatchSnapshot();
+```
+
+**Snapshot output example:**
+
+```html
+<my-component>
+  <mock:shadow-root>
+    <button class="primary">
+      <slot />
+    </button>
+  </mock:shadow-root>
+  Click me
+</my-component>
+```
+
+## Screenshot Testing
+
+Browser tests can include screenshot comparisons using Vitest's screenshot capabilities:
+
+```tsx
+import { render, h } from '@stencil/vitest';
+...
+const { root } = await render(<my-button variant="primary">Primary Button</my-button>);
+await expect(root).toMatchScreenshot();
+```
+
+Refer to Vitest's [screenshot testing documentation](https://vitest.dev/guide/snapshot.html#visual-snapshots) for more details.
+
+## CLI
+
+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
+# Build once, test once
+stencil-test
+
+# Watch mode (rebuilds on component changes, interactive Vitest)
+stencil-test --watch
+
+# Watch mode with dev server
+stencil-test --watch --serve
+
+# Production build before testing
+stencil-test --prod
+
+# Pass arguments to Vitest
+stencil-test --watch --coverage
+
+# Test specific files
+stencil-test button.spec.ts
+
+# Test specific project
+stencil-test --project browser
+```
+
+### CLI Options
+
+The `stencil-test` CLI supports most of Stencil's CLI options and all of Vitest CLI options
+
+- 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).
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.

package/dist/bin/stencil-test.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=stencil-test.d.ts.map

package/dist/bin/stencil-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stencil-test.d.ts","sourceRoot":"","sources":["../../bin/stencil-test.ts"],"names":[],"mappings":""}

package/dist/bin/stencil-test.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+function parseArgs(argv) {
+    const parsed = {
+        watch: false,
+        serve: false,
+        verbose: false,
+        debug: false,
+        prod: false,
+        coverage: false,
+        noCoverage: false,
+        ui: false,
+        help: false,
+        vitestArgs: [],
+        stencilArgs: [],
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        switch (arg) {
+            // Help
+            case '--help':
+            case '-h':
+                parsed.help = true;
+                i++;
+                break;
+            // Stencil flags
+            case '--watch':
+                parsed.watch = true;
+                i++;
+                break;
+            case '--serve':
+                parsed.serve = true;
+                i++;
+                break;
+            case '--port':
+                parsed.port = argv[i + 1];
+                i += 2;
+                break;
+            case '--verbose':
+            case '-v':
+                parsed.verbose = true;
+                i++;
+                break;
+            case '--debug':
+                parsed.debug = true;
+                i++;
+                break;
+            case '--prod':
+                parsed.prod = true;
+                i++;
+                break;
+            // Vitest flags
+            case '--project':
+                if (!parsed.project)
+                    parsed.project = [];
+                parsed.project.push(argv[i + 1]);
+                parsed.vitestArgs.push(arg, argv[i + 1]);
+                i += 2;
+                break;
+            case '--reporter':
+                if (!parsed.reporter)
+                    parsed.reporter = [];
+                parsed.reporter.push(argv[i + 1]);
+                parsed.vitestArgs.push(arg, argv[i + 1]);
+                i += 2;
+                break;
+            case '--coverage':
+                parsed.coverage = true;
+                parsed.vitestArgs.push(arg);
+                i++;
+                break;
+            case '--no-coverage':
+                parsed.noCoverage = true;
+                parsed.vitestArgs.push(arg);
+                i++;
+                break;
+            case '--ui':
+                parsed.ui = true;
+                parsed.vitestArgs.push(arg);
+                i++;
+                break;
+            // Unknown flags or test patterns - pass to vitest
+            default:
+                if (arg.startsWith('-')) {
+                    // Unknown flag - could be for either, but default to vitest
+                    parsed.vitestArgs.push(arg);
+                    // Check if next arg is a value for this flag
+                    if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+                        parsed.vitestArgs.push(argv[i + 1]);
+                        i += 2;
+                    }
+                    else {
+                        i++;
+                    }
+                }
+                else {
+                    // Positional arg - likely a test path pattern
+                    parsed.vitestArgs.push(arg);
+                    i++;
+                }
+                break;
+        }
+    }
+    return parsed;
+}
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+    console.log(`
+stencil-test - Integrated Stencil build and Vitest testing
+
+Usage:
+  stencil-test [options] [testPathPattern]
+
+Default (no flags): Build Stencil in dev mode and run tests once
+Watch mode: Build Stencil in watch mode and run Vitest with interactive features
+
+Stencil Options:
+  --watch              Run Stencil in watch mode (enables Vitest interactive mode)
+  --prod               Build in production mode (default: dev mode)
+  --serve              Start dev server (requires --watch)
+  --port <number>      Dev server port (default: 3333)
+  --verbose, -v        Show detailed logging
+  --debug              Enable Stencil debug mode
+
+Vitest Options:
+  --project <name>     Run tests for specific project
+  --reporter <name>    Use specified reporter (default, verbose, dot, json, etc.)
+  --coverage           Collect coverage information
+  --no-coverage        Disable coverage
+  --ui                 Enable Vitest UI
+  [testPathPattern]    Run only tests matching this pattern
+
+Interactive Watch Mode (when --watch is enabled):
+  Press 'p' to filter by filename pattern
+  Press 't' to filter by test name pattern  
+  Press 'f' to rerun only failed tests
+  Press 'u' to update snapshots
+  Press 'a' to rerun all tests
+  Press 'q' to quit
+
+Examples:
+  stencil-test                           # Build once, test once
+  stencil-test --watch                   # Watch mode with auto-testing
+  stencil-test --watch --serve           # Watch mode with dev server
+  stencil-test button.spec.ts            # Test specific file
+  stencil-test --project browser         # Test specific project
+  stencil-test --watch --coverage        # Watch with coverage
+  `);
+    process.exit(0);
+}
+let stencilProcess = null;
+let vitestProcess = null;
+let debounceTimer = null;
+let buildCount = 0;
+let isRunningTests = false;
+const DEBOUNCE_MS = 500;
+const cwd = process.cwd();
+const verbose = args.verbose;
+function log(message) {
+    console.log(`[stencil-test] ${message}`);
+}
+/**
+ * Runs Vitest tests with the configured arguments
+ * In watch mode, starts Vitest in its own watch mode for interactive features
+ * In non-watch mode, runs tests once
+ */
+function runTests() {
+    // Prevent overlapping test runs in non-watch mode
+    if (!args.watch && isRunningTests) {
+        if (verbose) {
+            log('Tests already running, skipping...');
+        }
+        return;
+    }
+    // Kill existing test process if running
+    if (vitestProcess) {
+        vitestProcess.kill();
+        vitestProcess = null;
+    }
+    isRunningTests = true;
+    if (verbose) {
+        log(`Running tests (build #${buildCount})...`);
+    }
+    else {
+        log('Running tests...');
+    }
+    // In watch mode, use Vitest's watch mode for interactive features
+    // In non-watch mode, use 'run' for a single test run
+    const vitestMode = args.watch ? 'watch' : 'run';
+    const commandArgs = ['vitest', vitestMode, ...args.vitestArgs].filter(Boolean);
+    if (verbose) {
+        log(`Command: npx ${commandArgs.join(' ')}`);
+    }
+    vitestProcess = spawn('npx', commandArgs, {
+        cwd,
+        stdio: 'inherit',
+        shell: true,
+        env: {
+            ...process.env,
+            NODE_ENV: 'test',
+        },
+    });
+    vitestProcess.on('exit', (code) => {
+        isRunningTests = false;
+        if (verbose) {
+            if (code === 0) {
+                log('Tests passed ✓');
+            }
+            else {
+                log(`Tests failed with code ${code}`);
+            }
+        }
+        vitestProcess = null;
+        // In one-time mode, exit after tests complete
+        if (!args.watch) {
+            process.exit(code || 0);
+        }
+    });
+    vitestProcess.on('error', (error) => {
+        isRunningTests = false;
+        console.error('[stencil-test] Failed to start test process:', error);
+        vitestProcess = null;
+    });
+}
+function handleStencilOutput(data) {
+    const output = data.toString();
+    process.stdout.write(output);
+    // Detect build completion
+    // Stencil outputs "build finished" on first build or "rebuild finished" in watch mode
+    if (output.includes('build finished') || output.includes('rebuild finished')) {
+        buildCount++;
+        if (verbose) {
+            log(`Build #${buildCount} finished`);
+        }
+        // Check if there were errors
+        const hasErrors = output.toLowerCase().includes('[ error ]');
+        if (hasErrors) {
+            if (verbose) {
+                log('Skipping tests due to build errors');
+            }
+            return;
+        }
+        // Run tests after the first successful build
+        // In watch mode, Vitest will automatically re-run when the dist/ files change
+        if (!vitestProcess) {
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+                if (verbose) {
+                    log('Debouncing initial test run');
+                }
+            }
+            debounceTimer = setTimeout(() => {
+                runTests();
+            }, DEBOUNCE_MS);
+        }
+    }
+}
+/**
+ * Clean up child processes and optionally exit with code.
+ */
+function cleanup(exitCode) {
+    log('Shutting down...');
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+    }
+    if (vitestProcess) {
+        vitestProcess.kill();
+        vitestProcess = null;
+    }
+    if (stencilProcess) {
+        stencilProcess.kill();
+        stencilProcess = null;
+    }
+    if (typeof exitCode === 'number') {
+        process.exit(exitCode);
+    }
+}
+// Set up signal handlers for clean shutdown
+process.on('SIGINT', () => cleanup());
+process.on('SIGTERM', () => cleanup());
+// Build Stencil arguments
+const stencilArgs = ['stencil', 'build'];
+// Add --dev by default, unless --prod is explicitly passed
+if (args.prod) {
+    stencilArgs.push('--prod');
+}
+else {
+    stencilArgs.push('--dev');
+}
+if (args.watch) {
+    stencilArgs.push('--watch');
+    log('Starting Stencil in watch mode...');
+    if (args.serve) {
+        stencilArgs.push('--serve');
+        if (args.port) {
+            stencilArgs.push('--port', args.port);
+        }
+    }
+}
+else {
+    log('Building Stencil...');
+}
+if (args.debug) {
+    stencilArgs.push('--debug');
+}
+// Add any additional stencil args
+stencilArgs.push(...args.stencilArgs);
+stencilProcess = spawn('npx', stencilArgs, {
+    cwd,
+    shell: true,
+});
+// Pipe stdout and watch for build completion
+stencilProcess.stdout?.on('data', handleStencilOutput);
+stencilProcess.stderr?.on('data', (data) => {
+    process.stderr.write(data);
+});
+stencilProcess.on('error', (error) => {
+    console.error('[stencil-test] Failed to start Stencil:', error);
+    process.exit(1);
+});
+stencilProcess.on('exit', (code) => {
+    if (verbose) {
+        log(`Stencil exited with code ${code}`);
+    }
+    // In one-time build mode, stencil exits after build
+    // Don't cleanup immediately - let tests finish first
+    if (!args.watch) {
+        stencilProcess = null;
+    }
+    else {
+        // In watch mode, stencil shouldn't exit - if it does, something went wrong
+        log(`Stencil exited unexpectedly with code ${code}`);
+        cleanup(code || 1);
+    }
+});
+// Watch mode: Vitest handles test file watching automatically
+// Stencil handles component file watching automatically
+if (args.watch && verbose) {
+    log('Watch mode enabled - Vitest will watch test files and Stencil will watch component files');
+}