@swedevtools/livedoc-vitest 0.2.0 → 0.3.0

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

@@ -1,231 +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`
+# 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/partial-testing.md

@@ -0,0 +1,77 @@
+# Tag-Scoped Partial Testing
+
+Use tags as the primary selector for incremental validation. File paths and test
+titles are fallback selectors when no stable capability tag exists.
+
+## Viewer Contract
+
+1. Publish at least one successful full run for the project and environment.
+2. Run the affected tags with `LIVEDOC_RUN_TYPE=partial`.
+3. The server stores the focused invocation and composes it over the latest full
+   baseline.
+4. The Viewer can show the Combined result or only that partial invocation.
+
+Tests omitted from a partial invocation keep their baseline result. Partial runs
+require server history and cannot be written directly as static JSON.
+
+## Configure a Tag Selector
+
+LiveDoc Vitest exposes tag filters through `livedoc.options.filters`. Use this
+setup convention so agents and scripts can select tags without editing source:
+
+```typescript
+// test/livedoc.setup.ts
+import { livedoc } from "@swedevtools/livedoc-vitest";
+
+const requestedTags = process.env.LIVEDOC_TAGS
+    ?.split(",")
+    .map((tag) => tag.trim())
+    .filter(Boolean)
+    .map((tag) => tag.startsWith("@") ? tag : `@${tag}`);
+
+if (requestedTags?.length) {
+    livedoc.options.filters.include = requestedTags;
+}
+```
+
+Register the file through Vitest `setupFiles`. `LIVEDOC_TAGS` is a project setup
+convention implemented by this file; the framework reads the resulting
+`filters.include` values.
+
+## Agent Workflow
+
+1. Identify the smallest stable capability tags affected by the code change.
+2. Prefer domain tags such as `@checkout`, `@pricing`, or `@authentication`.
+3. Do not add temporary `@changed` tags or rewrite tests solely for selection.
+4. Run the affected tags as a partial:
+
+```powershell
+$env:LIVEDOC_TAGS = "checkout,pricing"
+$env:LIVEDOC_RUN_TYPE = "partial"
+try {
+    pnpm exec vitest run
+}
+finally {
+    Remove-Item Env:\LIVEDOC_TAGS -ErrorAction SilentlyContinue
+    Remove-Item Env:\LIVEDOC_RUN_TYPE -ErrorAction SilentlyContinue
+}
+```
+
+```bash
+LIVEDOC_TAGS=checkout,pricing LIVEDOC_RUN_TYPE=partial pnpm exec vitest run
+```
+
+5. Use file or `-t` filtering only when the affected behavior has no suitable
+   tag.
+6. Run and publish a full suite before release, merge, or whenever the baseline
+   may be stale.
+
+## Failure Handling
+
+- No tests execute: verify the setup file is registered and tags include the
+  `@` prefix after normalization.
+- The Viewer loses unaffected results: the run was published as `full`; repeat
+  with `LIVEDOC_RUN_TYPE=partial`.
+- Combined view is unavailable: publish a full baseline with the same project
+  and environment first.
+- Static export fails: partial runs are server-only; use a full run for exports.