@swedevtools/livedoc-vitest 0.2.0 → 0.3.0

package/tools/skills/resources/playwright.md

@@ -1,148 +1,148 @@
-# Playwright Integration — Full Reference
-
-Browser-based testing with `@swedevtools/livedoc-vitest/playwright`.
-
-## Prerequisites
-
-```bash
-npm install -D playwright         # or: pnpm add -D playwright
-npx playwright install chromium   # install browser binary
-```
-
-## Import
-
-```typescript
-import { useBrowser, screenshot } from "@swedevtools/livedoc-vitest/playwright";
-```
-
-## useBrowser(options?)
-
-Manages browser lifecycle for the current feature file. **Call at module scope** (outside any scenario). Launches the browser in `beforeAll`, closes in `afterAll`.
-
-```typescript
-import { feature, scenario, given, when, Then as then } from "@swedevtools/livedoc-vitest";
-import { useBrowser, screenshot } from "@swedevtools/livedoc-vitest/playwright";
-
-const { page, context, browser } = useBrowser();
-
-feature("Viewer Navigation", () => {
-    scenario("Loading the homepage", () => {
-        when("navigating to the homepage", async (ctx) => {
-            await page().goto("http://localhost:3000");
-            await screenshot(page(), ctx);
-        });
-
-        then("the page title should be visible", async () => {
-            const title = await page().locator("h1").textContent();
-            expect(title).toBeTruthy();
-        });
-    });
-});
-```
-
-### Options
-
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `browser` | `'chromium' \| 'firefox' \| 'webkit'` | `'chromium'` | Browser engine |
-| `headless` | `boolean` | `true` | Run headless (set `false` for debugging) |
-| `viewport` | `{width, height}` | `1280×720` | Browser viewport size |
-| `freshContextPerScenario` | `boolean` | `false` | Create a fresh browser context for each scenario |
-
-### Return Value
-
-`useBrowser()` returns **getter functions**, not direct references:
-
-- `page()` — returns the current Playwright Page
-- `context()` — returns the current BrowserContext
-- `browser()` — returns the Browser instance
-
-```typescript
-const { page } = useBrowser({ headless: false });
-
-// ✅ CORRECT: Call page() inside a step
-when("clicking the button", async () => {
-    await page().click("button#submit");
-});
-
-// ❌ WRONG: page() at module scope — browser not launched yet
-const p = page(); // Will throw or return undefined
-```
-
-### Headed Mode (Debugging)
-
-```typescript
-const { page } = useBrowser({ headless: false });
-```
-
-The browser window stays visible for debugging. Combine with `scenario.only()` to focus on a single test.
-
-## screenshot(page, ctx, options?)
-
-Captures a screenshot and attaches it to the current step.
-
-```typescript
-when("viewing the dashboard", async (ctx) => {
-    await screenshot(page(), ctx);
-    // Auto-named: "viewing-the-dashboard-0.png"
-});
-```
-
-### Parameters
-
-- `page` — Playwright Page instance (use `page()` getter)
-- `ctx` — Step context from the step callback
-- `options.name` — Custom screenshot name (optional; auto-generated from step title if omitted)
-- `options.fullPage` — Capture full page vs viewport only (optional)
-
-### Custom Named Screenshots
-
-```typescript
-when("viewing the dashboard", async (ctx) => {
-    await screenshot(page(), ctx, { name: "dashboard-initial-load" });
-    // ... interact with page ...
-    await screenshot(page(), ctx, { name: "dashboard-after-filter" });
-});
-```
-
-## Global Setup for Dev Server
-
-When testing against a local dev server, use Vitest's `globalSetup` to start it:
-
-```typescript
-// vitest.config.ts
-export default defineConfig({
-    test: {
-        globalSetup: './global-setup.ts',
-    },
-});
-
-// global-setup.ts
-export async function setup() {
-    // Start your dev server, wait for it to be ready
-}
-export async function teardown() {
-    // Stop the server
-}
-```
-
-## CI Configuration
-
-```yaml
-# .github/workflows/test.yml
-- name: Install Playwright
-  run: npx playwright install --with-deps chromium
-- name: Run tests
-  run: npx vitest run
-```
-
-## Troubleshooting
-
-| Problem | Cause | Solution |
-| --- | --- | --- |
-| `Cannot find module 'playwright'` | Not installed | `npm install -D playwright` |
-| `Browser not found` | Binaries not installed | `npx playwright install chromium` |
-| `page() returns undefined` | Called at module scope | Call `page()` inside step callbacks only |
-| `useBrowser is not a function` | Wrong import path | Use `@swedevtools/livedoc-vitest/playwright` |
-| Tests timeout | Slow network/server | Increase vitest timeout, ensure server is running |
-| Screenshots are blank | Page not loaded | Add `await page().waitForLoadState()` before screenshot |
+# Playwright Integration — Full Reference
+
+Browser-based testing with `@swedevtools/livedoc-vitest/playwright`.
+
+## Prerequisites
+
+```bash
+npm install -D playwright         # or: pnpm add -D playwright
+npx playwright install chromium   # install browser binary
+```
+
+## Import
+
+```typescript
+import { useBrowser, screenshot } from "@swedevtools/livedoc-vitest/playwright";
+```
+
+## useBrowser(options?)
+
+Manages browser lifecycle for the current feature file. **Call at module scope** (outside any scenario). Launches the browser in `beforeAll`, closes in `afterAll`.
+
+```typescript
+import { feature, scenario, given, when, Then as then } from "@swedevtools/livedoc-vitest";
+import { useBrowser, screenshot } from "@swedevtools/livedoc-vitest/playwright";
+
+const { page, context, browser } = useBrowser();
+
+feature("Viewer Navigation", () => {
+    scenario("Loading the homepage", () => {
+        when("navigating to the homepage", async (ctx) => {
+            await page().goto("http://localhost:3000");
+            await screenshot(page(), ctx);
+        });
+
+        then("the page title should be visible", async () => {
+            const title = await page().locator("h1").textContent();
+            expect(title).toBeTruthy();
+        });
+    });
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `browser` | `'chromium' \| 'firefox' \| 'webkit'` | `'chromium'` | Browser engine |
+| `headless` | `boolean` | `true` | Run headless (set `false` for debugging) |
+| `viewport` | `{width, height}` | `1280×720` | Browser viewport size |
+| `freshContextPerScenario` | `boolean` | `false` | Create a fresh browser context for each scenario |
+
+### Return Value
+
+`useBrowser()` returns **getter functions**, not direct references:
+
+- `page()` — returns the current Playwright Page
+- `context()` — returns the current BrowserContext
+- `browser()` — returns the Browser instance
+
+```typescript
+const { page } = useBrowser({ headless: false });
+
+// ✅ CORRECT: Call page() inside a step
+when("clicking the button", async () => {
+    await page().click("button#submit");
+});
+
+// ❌ WRONG: page() at module scope — browser not launched yet
+const p = page(); // Will throw or return undefined
+```
+
+### Headed Mode (Debugging)
+
+```typescript
+const { page } = useBrowser({ headless: false });
+```
+
+The browser window stays visible for debugging. Combine with `scenario.only()` to focus on a single test.
+
+## screenshot(page, ctx, options?)
+
+Captures a screenshot and attaches it to the current step.
+
+```typescript
+when("viewing the dashboard", async (ctx) => {
+    await screenshot(page(), ctx);
+    // Auto-named: "viewing-the-dashboard-0.png"
+});
+```
+
+### Parameters
+
+- `page` — Playwright Page instance (use `page()` getter)
+- `ctx` — Step context from the step callback
+- `options.name` — Custom screenshot name (optional; auto-generated from step title if omitted)
+- `options.fullPage` — Capture full page vs viewport only (optional)
+
+### Custom Named Screenshots
+
+```typescript
+when("viewing the dashboard", async (ctx) => {
+    await screenshot(page(), ctx, { name: "dashboard-initial-load" });
+    // ... interact with page ...
+    await screenshot(page(), ctx, { name: "dashboard-after-filter" });
+});
+```
+
+## Global Setup for Dev Server
+
+When testing against a local dev server, use Vitest's `globalSetup` to start it:
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+    test: {
+        globalSetup: './global-setup.ts',
+    },
+});
+
+// global-setup.ts
+export async function setup() {
+    // Start your dev server, wait for it to be ready
+}
+export async function teardown() {
+    // Stop the server
+}
+```
+
+## CI Configuration
+
+```yaml
+# .github/workflows/test.yml
+- name: Install Playwright
+  run: npx playwright install --with-deps chromium
+- name: Run tests
+  run: npx vitest run
+```
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+| --- | --- | --- |
+| `Cannot find module 'playwright'` | Not installed | `npm install -D playwright` |
+| `Browser not found` | Binaries not installed | `npx playwright install chromium` |
+| `page() returns undefined` | Called at module scope | Call `page()` inside step callbacks only |
+| `useBrowser is not a function` | Wrong import path | Use `@swedevtools/livedoc-vitest/playwright` |
+| Tests timeout | Slow network/server | Increase vitest timeout, ensure server is running |
+| Screenshots are blank | Page not loaded | Add `await page().waitForLoadState()` before screenshot |

package/tools/skills/resources/reporter-config.md

@@ -1,163 +1,213 @@
-# Reporter Configuration — Full Reference
-
-Configure LiveDoc reporters for console output, real-time viewer streaming, JSON export, and static HTML reports.
-
-## Available Reporters
-
-| Reporter | Purpose | Import |
-| --- | --- | --- |
-| `LiveDocSpecReporter` | Console output + auto-discover viewer | `@swedevtools/livedoc-vitest/reporter` |
-| `LiveDocViewerReporter` | Stream to viewer only (no console) | `@swedevtools/livedoc-vitest/reporter` |
-| `JsonReporter` | Write JSON file for static export | `@swedevtools/livedoc-vitest/reporter` |
-| `SilentReporter` | Suppress all output | `@swedevtools/livedoc-vitest/reporter` |
-
-## LiveDocSpecReporter
-
-The primary reporter. Produces structured Gherkin-style console output and auto-discovers a running LiveDoc Viewer server.
-
-### Simplest Config
-
-```typescript
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-    test: {
-        reporters: [
-            ["@swedevtools/livedoc-vitest/reporter", { detailLevel: "spec+summary+headers" }],
-        ],
-    },
-});
-```
-
-### Detail Levels
-
-Combinable with `+`:
-
-| Level | Output |
-| --- | --- |
-| `spec` | Full step-by-step output |
-| `summary` | Pass/fail/skip counts |
-| `headers` | Feature and scenario titles |
-| `list` | One-line-per-test list |
-| `silent` | No output |
-
-Examples: `"spec+summary+headers"`, `"list+headers"`, `"summary"`
-
-### Explicit Publish Config
-
-```typescript
-import { LiveDocSpecReporter } from "@swedevtools/livedoc-vitest/reporter";
-
-export default defineConfig({
-    test: {
-        reporters: [
-            new LiveDocSpecReporter({
-                detailLevel: "spec+summary+headers",
-                publish: {
-                    enabled: true,
-                    server: "http://localhost:3000",
-                    project: "my-project",
-                    environment: "local",
-                },
-            }),
-        ],
-    },
-});
-```
-
-### Auto-Discovery Priority
-
-The reporter automatically finds the viewer server:
-
-1. **Environment variables**: `LIVEDOC_SERVER_URL` or `LIVEDOC_PUBLISH_SERVER`
-2. **Explicit config**: `publish.server` in reporter options
-3. **Discovery**: `discoverServer()` fallback from `@swedevtools/livedoc-server`
-
-### Additional Options
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `detailLevel` | string | Output detail level (see above) |
-| `output` | string | Write output to file |
-| `removeHeaderText` | string | Strip text from headers (monorepo prefix) |
-| `colors` | boolean | Enable/disable ANSI colors |
-| `postReporters` | `IPostReporter[]` | Chain additional reporters after this one |
-
-## LiveDocViewerReporter
-
-Streams results to the LiveDoc Viewer in real-time without console output. Use when you want viewer integration only.
-
-```typescript
-import { LiveDocViewerReporter } from "@swedevtools/livedoc-vitest/reporter";
-
-export default defineConfig({
-    test: {
-        reporters: [
-            new LiveDocViewerReporter({
-                server: "http://localhost:3000",
-                project: "my-project",
-                environment: "local",
-            }),
-        ],
-    },
-});
-```
-
-## JsonReporter
-
-Writes test results to a JSON file. Used for CI/CD static report generation.
-
-```typescript
-import { JsonReporter } from "@swedevtools/livedoc-vitest/reporter";
-
-export default defineConfig({
-    test: {
-        reporters: [
-            new JsonReporter({ outputFile: "test-results.json" }),
-        ],
-    },
-});
-```
-
-## Static HTML Export
-
-Generate a self-contained HTML report from a JSON results file:
-
-```bash
-npx livedoc-viewer export -i test-results.json -o report.html
-```
-
-### CI/CD Pipeline
-
-```yaml
-steps:
-    - name: Run tests with JSON output
-      run: npx vitest run --config vitest.config.json.ts
-
-    - name: Generate HTML report
-      run: npx livedoc-viewer export -i test-results.json -o report.html
-
-    - name: Upload report
-      uses: actions/upload-artifact@v4
-      with:
-          name: test-report
-          path: report.html
-```
-
-### Environment-Driven Config
-
-Use environment variables for flexible CI configurations:
-
-```json
-{
-    "scripts": {
-        "test:spec": "cross-env LIVEDOC_DETAIL_LEVEL=spec+headers vitest run",
-        "test:list": "cross-env LIVEDOC_DETAIL_LEVEL=list+headers vitest run",
-        "test:summary": "cross-env LIVEDOC_DETAIL_LEVEL=summary+headers vitest run"
-    }
-}
-```
-
-## Backward Compatibility
-
-`LiveDocServerReporter` is a deprecated re-export of `LiveDocSpecReporter`. Old configs still work.
+# Reporter Configuration — Full Reference
+
+Configure LiveDoc reporters for console output, real-time viewer streaming, JSON export, and static HTML reports.
+
+## Available Reporters
+
+| Reporter | Purpose | Import |
+| --- | --- | --- |
+| `LiveDocSpecReporter` | Console output + auto-discover viewer | `@swedevtools/livedoc-vitest/reporter` |
+| `LiveDocViewerReporter` | Stream to viewer only (no console) | `@swedevtools/livedoc-vitest/reporter` |
+| `JsonReporter` | Write JSON file for static export | `@swedevtools/livedoc-vitest/reporter` |
+| `SilentReporter` | Suppress all output | `@swedevtools/livedoc-vitest/reporter` |
+
+## LiveDocSpecReporter
+
+The primary reporter. Produces structured Gherkin-style console output and auto-discovers a running LiveDoc Viewer server.
+
+### Simplest Config
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        reporters: [
+            ["@swedevtools/livedoc-vitest/reporter", { detailLevel: "spec+summary+headers" }],
+        ],
+    },
+});
+```
+
+### Detail Levels
+
+Combinable with `+`:
+
+| Level | Output |
+| --- | --- |
+| `spec` | Full step-by-step output |
+| `summary` | Pass/fail/skip counts |
+| `headers` | Feature and scenario titles |
+| `list` | One-line-per-test list |
+| `silent` | No output |
+
+Examples: `"spec+summary+headers"`, `"list+headers"`, `"summary"`
+
+### Explicit Publish Config
+
+```typescript
+import { LiveDocSpecReporter } from "@swedevtools/livedoc-vitest/reporter";
+
+export default defineConfig({
+    test: {
+        reporters: [
+            new LiveDocSpecReporter({
+                detailLevel: "spec+summary+headers",
+                publish: {
+                    enabled: true,
+                    server: "http://localhost:3100",
+                    project: "my-project",
+                    environment: "local",
+                },
+            }),
+        ],
+    },
+});
+```
+
+### Auto-Discovery Priority
+
+The reporter automatically finds the viewer server:
+
+1. **Environment variables**: `LIVEDOC_SERVER_URL` or `LIVEDOC_PUBLISH_SERVER`
+2. **Explicit config**: `publish.server` in reporter options
+3. **Discovery**: `discoverServer()` fallback from `@swedevtools/livedoc-server`
+4. **Default local viewer**: health check on `http://localhost:3100`
+
+Project and environment can also be set with `LIVEDOC_PROJECT` and `LIVEDOC_ENVIRONMENT`.
+
+### Coverage Evidence
+
+LiveDoc can attach coverage artifacts to the completed `TestRunV1` as supporting evidence. Coverage never changes the run pass/fail status; threshold misses are reported as warnings.
+
+Install the provider that matches the Vitest version:
+
+```bash
+npm install --save-dev @vitest/coverage-v8
+```
+
+```typescript
+import { LiveDocSpecReporter } from "@swedevtools/livedoc-vitest/reporter";
+
+export default defineConfig({
+    test: {
+        reporters: [
+            new LiveDocSpecReporter({
+                detailLevel: "spec+summary+headers",
+                coverage: {
+                    enabled: true,
+                    thresholds: { lines: 80, branches: 70 },
+                },
+            }),
+        ],
+        coverage: {
+            enabled: true,
+            provider: "v8",
+            reporter: ["text", "html", "json-summary"],
+        },
+    },
+});
+```
+
+Run `npx vitest run --coverage`. LiveDoc consumes Vitest's in-memory coverage map during the reporter lifecycle. File reporters are optional fallbacks for static export and external coverage tooling.
+
+Supported fallback artifacts:
+
+| Artifact | Auto-detected path | Notes |
+| --- | --- | --- |
+| Istanbul summary JSON | `coverage/coverage-summary.json` | Preferred for run and file summaries |
+| LCOV | `coverage/lcov.info` | Useful when summary JSON is not available |
+
+Use `coverage.artifactPath` or `LIVEDOC_COVERAGE_PATH` when the artifact is outside the standard coverage directory. Use `LIVEDOC_COVERAGE=true` to request diagnostics when coverage is expected but no supported artifact is found.
+
+### Additional Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `detailLevel` | string | Output detail level (see above) |
+| `output` | string | Write output to file |
+| `removeHeaderText` | string | Strip text from headers (monorepo prefix) |
+| `colors` | boolean | Enable/disable ANSI colors |
+| `postReporters` | `IPostReporter[]` | Chain additional reporters after this one |
+
+## LiveDocViewerReporter
+
+Streams results to the LiveDoc Viewer in real-time without console output. Use when you want viewer integration only.
+
+```typescript
+import { LiveDocViewerReporter } from "@swedevtools/livedoc-vitest/reporter";
+
+export default defineConfig({
+    test: {
+        reporters: [
+            new LiveDocViewerReporter({
+                server: "http://localhost:3100",
+                project: "my-project",
+                environment: "local",
+                runType: "full",
+            }),
+        ],
+    },
+});
+```
+
+Set `runType: "partial"` or `LIVEDOC_RUN_TYPE=partial` for an isolated development run after a full baseline has been published. The Viewer preserves the baseline and lets users switch between the combined snapshot and only that partial invocation. Partial runs require server history and cannot be written directly as static JSON.
+
+## JsonReporter
+
+Writes test results to a JSON file. Used for CI/CD static report generation.
+
+```typescript
+import { JsonReporter } from "@swedevtools/livedoc-vitest/reporter";
+
+export default defineConfig({
+    test: {
+        reporters: [
+            new JsonReporter({ outputFile: "test-results.json" }),
+        ],
+    },
+});
+```
+
+## Static HTML Export
+
+Generate a self-contained HTML report from a JSON results file:
+
+```bash
+npx livedoc-viewer export -i test-results.json -o report.html
+```
+
+### CI/CD Pipeline
+
+```yaml
+steps:
+    - name: Run tests with JSON output
+      run: npx vitest run --config vitest.config.json.ts
+
+    - name: Generate HTML report
+      run: npx livedoc-viewer export -i test-results.json -o report.html
+
+    - name: Upload report
+      uses: actions/upload-artifact@v4
+      with:
+          name: test-report
+          path: report.html
+```
+
+### Environment-Driven Config
+
+Use environment variables for flexible CI configurations:
+
+```json
+{
+    "scripts": {
+        "test:spec": "cross-env LIVEDOC_DETAIL_LEVEL=spec+headers vitest run",
+        "test:list": "cross-env LIVEDOC_DETAIL_LEVEL=list+headers vitest run",
+        "test:summary": "cross-env LIVEDOC_DETAIL_LEVEL=summary+headers vitest run"
+    }
+}
+```
+
+## Backward Compatibility
+
+`LiveDocServerReporter` is a deprecated re-export of `LiveDocSpecReporter`. Old configs still work.