@swedevtools/livedoc-vitest 0.2.0

package/tools/skills/resources/bdd-features.md

@@ -0,0 +1,231 @@
+# BDD Features — Full Reference
+
+Complete reference for writing BDD/Gherkin-style tests with `@swedevtools/livedoc-vitest`.
+
+## Keywords
+
+```
+feature → scenario | scenarioOutline | background → given | when | then | and | but
+```
+
+All blocks receive a `ctx` parameter with framework metadata.
+
+## Import Block
+
+```typescript
+import { feature, scenario, scenarioOutline, background, given, when, Then as then, and, but } from "@swedevtools/livedoc-vitest";
+```
+
+**CRITICAL**: Import `Then` (uppercase) and alias as `then` (lowercase). ESM thenable detection requires the uppercase export name.
+
+## Feature
+
+```typescript
+feature("Shopping Cart", (ctx) => {
+    // ctx.feature → { filename, title, description, tags }
+});
+```
+
+## Scenario
+
+```typescript
+scenario("Adding items to cart", (ctx) => {
+    // ctx.scenario → { title, description, tags, given?, steps }
+    given("...", (ctx) => { /* ctx.step available */ });
+    when("...", (ctx) => { /* ctx.step available */ });
+    then("...", (ctx) => { /* ctx.step available */ });
+});
+```
+
+## Background
+
+Shared setup that runs before every scenario in a feature:
+
+```typescript
+feature("User Dashboard", () => {
+    background("Authenticated user", (ctx) => {
+        given("the user is logged in", () => {
+            user = await login();
+        });
+
+        // Optional cleanup — runs after each scenario
+        ctx.afterBackground(() => {
+            user = null;
+        });
+    });
+
+    scenario("Viewing the dashboard", () => {
+        // 'given' from background runs first
+        when("...", () => { });
+        then("...", () => { });
+    });
+});
+```
+
+**Note**: `background()` requires a title as the first argument.
+
+## Descriptions and Tags
+
+Lines after the first line in titles provide descriptions and tags:
+
+```typescript
+feature(`Shopping Cart Checkout
+    @checkout @critical
+    Business rules for the shopping cart checkout flow.
+    Covers GST calculation, shipping tiers, and discount codes.
+    `, (ctx) => {
+
+    scenario(`Free shipping for large orders
+        Orders over $100 qualify for free shipping in Australia.
+        `, (ctx) => {
+        // steps...
+    });
+});
+```
+
+- **First line** = title
+- **Lines starting with `@`** = tags (used for filtering)
+- **Remaining lines** = description (appears in output and reports)
+
+**Always add descriptions** to `feature` blocks for context. Optionally to `scenario` blocks.
+
+## Value Extraction
+
+### Quoted Values — auto-extracted, type-coerced
+
+```typescript
+given("user has '100' items and active is 'true'", (ctx) => {
+    const [count, isActive] = ctx.step.values;
+    // count = 100 (number), isActive = true (boolean)
+});
+```
+
+### Named Parameters — `<name:value>` syntax
+
+```typescript
+given("a user with <email:john@test.com> and <age:25>", (ctx) => {
+    const email = ctx.step.params.email; // "john@test.com"
+    const age = ctx.step.params.age;     // 25
+});
+```
+
+### Data Tables
+
+```typescript
+given(`users:
+    | name  | age |
+    | Alice |  30 |
+    | Bob   |  25 |
+    `, (ctx) => {
+    // ctx.step.table => [{name: "Alice", age: 30}, {name: "Bob", age: 25}]
+    // ctx.step.tableAsEntity => (2-col table as single object)
+    // ctx.step.tableAsSingleList => (first column as flat array)
+    // ctx.step.dataTable => (raw 2D array)
+});
+```
+
+### Doc Strings
+
+```typescript
+given(`config:
+    """
+    {"debug": true, "level": 5}
+    """
+    `, (ctx) => {
+    const raw = ctx.step.docString;         // '{"debug": true, "level": 5}'
+    const parsed = ctx.step.docStringAsEntity; // {debug: true, level: 5}
+});
+```
+
+## ScenarioOutline with Examples
+
+Data-driven scenarios. Each row in the Examples table creates a separate test:
+
+```typescript
+scenarioOutline(`Validate inputs
+    Examples:
+    | input | expected |
+    | foo   | true     |
+    | bar   | false    |
+    `, (ctx) => {
+    when("checking <input>", (ctx) => {
+        result = validate(ctx.example.input);
+    });
+    then("result is <expected>", (ctx) => {
+        expect(result).toBe(ctx.example.expected);
+    });
+});
+```
+
+Access example data via `ctx.example.<columnName>`. Values are type-coerced.
+
+## Step Attachment API
+
+Attach files, screenshots, and data to steps. Attachments appear in the LiveDoc Viewer.
+
+```typescript
+// Attach JSON data
+ctx.step.attachJSON(data, "API Response");
+
+// Attach a screenshot (base64 PNG)
+ctx.step.attachScreenshot(base64Data, "Login Page");
+
+// Attach arbitrary data
+ctx.step.attach(base64Data, { mimeType: "image/png", kind: "image", title: "Chart" });
+```
+
+**Methods:**
+- `attach(base64Data, options?)` — options: `{mimeType, kind: 'image'|'screenshot'|'file', title}`
+- `attachScreenshot(base64Data, title?)` — convenience for PNG screenshots
+- `attachJSON(data, title?)` — convenience for JSON data
+
+Read attachments: `ctx.step.attachments` (read-only array)
+
+## Async Rules
+
+- **Only step callbacks support `async`** (`given`, `when`, `then`, `and`, `but`)
+- `feature`, `scenario`, `scenarioOutline`, `background` must be **synchronous**
+
+```typescript
+when("data is fetched", async (ctx) => {
+    result = await fetchData();  // ✅ OK
+});
+
+scenario("Test", async (ctx) => { /* ❌ NOT ALLOWED */ });
+```
+
+## Context Reference
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `ctx.feature` | `FeatureContext` | `{filename, title, description, tags}` |
+| `ctx.scenario` | `ScenarioContext` | `{title, description, tags, given?, steps}` |
+| `ctx.step` | `StepContext` | `{title, type, values, docString, table, ...}` |
+| `ctx.example` | `object` | Current example row (scenarioOutline only) |
+| `ctx.background` | `BackgroundContext` | Background metadata |
+| `ctx.afterBackground(fn)` | function | Register cleanup (background only) |
+
+### StepContext Properties
+
+| Property | Returns |
+| --- | --- |
+| `values` | Coerced quoted values array |
+| `valuesRaw` | Raw string values |
+| `params` | Coerced named values object `<n:v>` |
+| `paramsRaw` | Raw named values string object |
+| `docString` | Raw doc string content |
+| `docStringAsEntity` | Parsed JSON or undefined |
+| `table` | Headers as keys, array of row objects |
+| `tableAsEntity` | 2-col table as single object |
+| `tableAsSingleList` | First column as flat array |
+| `dataTable` | Raw 2D array |
+| `attachments` | Read-only `Attachment[]` |
+
+## Validation Checklist
+
+- [ ] All test data appears in step title strings (self-documenting)
+- [ ] Descriptions provided on `feature` blocks for context
+- [ ] Values extracted via `ctx.step.values`, `ctx.step.params`, or `ctx.example`
+- [ ] `Then` imported as uppercase, aliased to lowercase `then`
+- [ ] Async only on step callbacks
+- [ ] File name ends in `.Spec.ts`

package/tools/skills/resources/playwright.md

@@ -0,0 +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 |

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

@@ -0,0 +1,163 @@
+# 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.

package/tools/skills/resources/specifications.md

@@ -0,0 +1,159 @@
+# Specifications — Full Reference
+
+Complete reference for writing MSpec-style specification/rule tests with `@swedevtools/livedoc-vitest`.
+
+## Keywords
+
+```
+specification → rule | ruleOutline
+```
+
+## Import Block
+
+```typescript
+import { specification, rule, ruleOutline } from "@swedevtools/livedoc-vitest";
+```
+
+## Specification
+
+Top-level container grouping related rules:
+
+```typescript
+specification("Calculator Operations", (ctx) => {
+    // ctx.specification → { title, description, tags }
+});
+```
+
+## Rule
+
+Individual test cases with direct assertions:
+
+```typescript
+specification("Calculator Operations", () => {
+    rule("Adding '5' and '3' returns '8'", (ctx) => {
+        const [a, b, expected] = ctx.rule.values; // [5, 3, 8]
+        expect(a + b).toBe(expected);
+    });
+});
+```
+
+## Value Extraction
+
+### Quoted Values — auto-extracted, type-coerced
+
+```typescript
+rule("Adding '5' and '3' returns '8'", (ctx) => {
+    const [a, b, expected] = ctx.rule.values;
+    // a = 5 (number), b = 3, expected = 8
+});
+```
+
+### Named Parameters — `<name:value>` syntax
+
+```typescript
+rule("Subtracting <b:3> from <a:10> returns <expected:7>", (ctx) => {
+    const a = ctx.rule.params.a;             // 10
+    const b = ctx.rule.params.b;             // 3
+    expect(a - b).toBe(ctx.rule.params.expected); // 7
+});
+```
+
+## RuleOutline with Examples
+
+Data-driven rules. Each row in the Examples table creates a separate test:
+
+```typescript
+ruleOutline(`Discount calculations
+    Examples:
+    | price | discount | expected |
+    |   100 |       10 |       90 |
+    |   200 |       25 |      150 |
+    `, (ctx) => {
+    const result = ctx.example.price - (ctx.example.price * ctx.example.discount / 100);
+    expect(result).toBe(ctx.example.expected);
+});
+```
+
+### Combining Title Values and Example Data
+
+RuleOutline supports both title values and example table data:
+
+```typescript
+ruleOutline(`Discount of '10' percent applies to orders over '100' dollars
+    Examples:
+    | orderTotal | expectedDiscount |
+    |        150 |               15 |
+    |        200 |               20 |
+    `, (ctx) => {
+    const [discountPct, threshold] = ctx.rule.values; // From title: [10, 100]
+    const discount = ctx.example.orderTotal * (discountPct / 100); // From table
+    expect(discount).toBe(ctx.example.expectedDiscount);
+});
+```
+
+### Named Params in RuleOutline
+
+```typescript
+ruleOutline(`Applying <operation:multiply> with factor <factor:3>
+    Examples:
+    | input | expected |
+    |     5 |       15 |
+    |    10 |       30 |
+    `, (ctx) => {
+    expect(ctx.rule.params.operation).toBe("multiply");
+    expect(ctx.example.input * ctx.rule.params.factor).toBe(ctx.example.expected);
+});
+```
+
+## Descriptions and Tags
+
+```typescript
+specification(`Email Validation
+    @validation
+    Rules for validating email addresses across formats.
+    `, (ctx) => {
+    // rules...
+});
+```
+
+- **First line** = title
+- **Lines starting with `@`** = tags
+- **Remaining lines** = description
+
+## Async Rules
+
+`rule` callbacks support `async`. `specification` callbacks must be **synchronous**.
+
+```typescript
+rule("Fetching user returns valid data", async (ctx) => {
+    const user = await fetchUser(1);
+    expect(user.name).toBeTruthy();  // ✅ OK
+});
+
+specification("Test", async (ctx) => { /* ❌ NOT ALLOWED */ });
+```
+
+## Context Reference
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `ctx.specification` | `SpecificationContext` | `{title, description, tags}` |
+| `ctx.rule` | `RuleContext` | `{title, description, tags, specification, values, valuesRaw, params, paramsRaw}` |
+| `ctx.example` | `object` | Current example row (ruleOutline only) |
+
+### RuleContext Properties
+
+| Property | Returns |
+| --- | --- |
+| `values` | Coerced quoted values array |
+| `valuesRaw` | Raw string values |
+| `params` | Coerced named values object `<n:v>` |
+| `paramsRaw` | Raw named values string object |
+
+## Validation Checklist
+
+- [ ] All test data appears in rule title strings (self-documenting)
+- [ ] Descriptions provided on `specification` blocks
+- [ ] Values extracted via `ctx.rule.values`, `ctx.rule.params`, or `ctx.example`
+- [ ] Async only on `rule` callbacks, not `specification`
+- [ ] File name ends in `.Spec.ts`