executable-stories-playwright 7.0.1 → 7.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-playwright",
-  "version": "7.0.1",
+  "version": "7.0.2",
   "description": "BDD-style executable stories for Playwright Test with documentation generation",
   "type": "module",
   "sideEffects": false,
@@ -20,11 +20,13 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "skills",
+    "README.md",
+    "bin"
   ],
   "peerDependencies": {
     "@playwright/test": ">=1.58.2",
-    "executable-stories-formatters": "^0.6.1",
+    "executable-stories-formatters": "^0.6.2",
     "autotel": ">=2.21.0"
   },
   "peerDependenciesMeta": {
@@ -39,7 +41,7 @@
     "@types/node": "^25.3.2",
     "tsup": "^8.5.1",
     "typescript": "~5.9.3",
-    "executable-stories-formatters": "0.6.1"
+    "executable-stories-formatters": "0.6.2"
   },
   "repository": {
     "type": "git",
@@ -53,6 +55,9 @@
     "documentation",
     "executable-stories"
   ],
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "build": "tsup",
     "type-check": "tsc --noEmit",

package/skills/playwright-converting-tests/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: playwright-converting-tests
+description: >
+  Incrementally adopt executable-stories in Playwright. Add story.init(testInfo)
+  and step markers to existing spec blocks. File naming .story.spec.ts.
+  TestInfo from test callback second argument. Progressive enhancement.
+type: lifecycle
+library: executable-stories-playwright
+library_version: "7.0.1"
+requires:
+  - playwright-story-api
+sources:
+  - "jagreehal/executable-stories:apps/docs-site/src/content/docs/guides/converting-playwright.md"
+---
+
+This skill builds on playwright-story-api. Read playwright-story-api first.
+
+# Converting Existing Playwright Tests
+
+## Setup
+
+Install the packages and configure the reporter:
+
+```bash
+npm install -D executable-stories-playwright executable-stories-formatters
+```
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  reporter: [
+    ["html"],
+    ["executable-stories-playwright/reporter", { formats: ["markdown"] }],
+  ],
+});
+```
+
+## Core Patterns
+
+### Step 1: Rename the file
+
+```
+# Before
+tests/login.spec.ts
+
+# After
+tests/login.story.spec.ts
+```
+
+### Step 2: Add story.init() and step markers
+
+```typescript
+// Before
+import { test, expect } from "@playwright/test";
+
+test("logs in successfully", async ({ page }) => {
+  await page.goto("/login");
+  await page.fill("#email", "user@example.com");
+  await page.fill("#password", "secret");
+  await page.click("#submit");
+  await expect(page.locator("h1")).toHaveText("Dashboard");
+});
+```
+
+```typescript
+// After
+import { test, expect } from "@playwright/test";
+import { story, given, when, then } from "executable-stories-playwright";
+
+test("logs in successfully", async ({ page }, testInfo) => {
+  story.init(testInfo);
+
+  given("the login page is loaded");
+  await page.goto("/login");
+
+  when("valid credentials are entered");
+  await page.fill("#email", "user@example.com");
+  await page.fill("#password", "secret");
+  await page.click("#submit");
+
+  then("the dashboard is shown");
+  await expect(page.locator("h1")).toHaveText("Dashboard");
+});
+```
+
+Key change: add `testInfo` as the second parameter in the test callback.
+
+### Step 3: Minimal story
+
+```typescript
+test("loads homepage", async ({ page }, testInfo) => {
+  story.init(testInfo);
+  await page.goto("/");
+  await expect(page).toHaveTitle("My App");
+});
+```
+
+### Step 4: Add doc entries
+
+```typescript
+test("shows product details", async ({ page }, testInfo) => {
+  story.init(testInfo, { tags: ["e2e", "products"] });
+
+  given("the product page is loaded");
+  await page.goto("/products/123");
+
+  then("the product details are shown");
+  story.screenshot({ path: "screenshots/product.png", alt: "Product page" });
+  story.json({ label: "Product", value: { id: 123, name: "Widget" } });
+});
+```
+
+### Suite headings from test.describe
+
+```typescript
+test.describe("Authentication", () => {
+  test("valid login", async ({ page }, testInfo) => {
+    story.init(testInfo);
+    // "Authentication" becomes a ## heading in docs
+  });
+});
+```
+
+## Common Mistakes
+
+### HIGH Using .story.test.ts instead of .story.spec.ts
+
+Wrong: `tests/login.story.test.ts`
+Correct: `tests/login.story.spec.ts`
+
+Playwright convention uses `.spec.ts`. The reporter filters accordingly.
+
+Source: CLAUDE.md — file naming conventions
+
+### HIGH Forgetting testInfo parameter
+
+Wrong:
+
+```typescript
+test("my test", async ({ page }) => {
+  story.init();  // No testInfo
+});
+```
+
+Correct:
+
+```typescript
+test("my test", async ({ page }, testInfo) => {
+  story.init(testInfo);
+});
+```
+
+`testInfo` is the second parameter of Playwright's test callback. Without it, story metadata is not linked to the test.
+
+Source: packages/executable-stories-playwright/src/story-api.ts

package/skills/playwright-reporter-setup/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: playwright-reporter-setup
+description: >
+  Configure Playwright custom reporter for executable-stories-playwright.
+  playwright.config.ts reporter array. Default export from
+  executable-stories-playwright/reporter. Output formats, directory, naming.
+  Aggregated and colocated modes. rawRunPath for CLI.
+type: core
+library: executable-stories-playwright
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-playwright/src/reporter.ts"
+---
+
+# executable-stories-playwright — Reporter Setup
+
+## Setup
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  reporter: [
+    ["html"],
+    [
+      "executable-stories-playwright/reporter",
+      {
+        formats: ["markdown", "html"],
+        outputDir: "docs",
+        outputName: "user-stories",
+      },
+    ],
+  ],
+});
+```
+
+Peer dependency: `executable-stories-formatters` must be installed.
+
+## Core Patterns
+
+### Minimal config
+
+```typescript
+export default defineConfig({
+  reporter: [
+    ["html"],
+    ["executable-stories-playwright/reporter", { formats: ["markdown"] }],
+  ],
+});
+```
+
+### Full options
+
+```typescript
+export default defineConfig({
+  reporter: [
+    ["html"],
+    [
+      "executable-stories-playwright/reporter",
+      {
+        formats: ["markdown", "html", "junit", "cucumber-json"],
+        outputDir: "reports",
+        outputName: "test-results",
+        output: {
+          mode: "aggregated",
+        },
+        markdown: {
+          title: "User Stories",
+          includeStatusIcons: true,
+          includeErrors: true,
+          includeMetadata: true,
+          sortScenarios: "source",
+        },
+        html: {
+          title: "Test Report",
+          darkMode: true,
+          searchable: true,
+          embedScreenshots: true,
+        },
+        rawRunPath: "reports/raw-run.json",
+      },
+    ],
+  ],
+});
+```
+
+### Annotation-based metadata
+
+The reporter reads story metadata from test annotations with `type: "story-meta"`. This is handled automatically when using `story.init(testInfo)` — no manual annotation is needed.
+
+## Common Mistakes
+
+### HIGH Using default export syntax incorrectly
+
+Wrong:
+
+```typescript
+import StoryReporter from "executable-stories-playwright/reporter";
+
+export default defineConfig({
+  reporter: [
+    ["html"],
+    [new StoryReporter({ formats: ["markdown"] })],
+  ],
+});
+```
+
+Correct:
+
+```typescript
+export default defineConfig({
+  reporter: [
+    ["html"],
+    [
+      "executable-stories-playwright/reporter",
+      { formats: ["markdown"] },
+    ],
+  ],
+});
+```
+
+Playwright's reporter config expects a string path and options object tuple, not a class instance. Playwright instantiates the reporter itself from the path.
+
+Source: packages/executable-stories-playwright/src/reporter.ts
+
+### MEDIUM Default format is cucumber-json, not markdown
+
+The default `formats` is `["cucumber-json"]`. Always specify `formats: ["markdown"]` explicitly to get readable markdown output.
+
+Source: packages/executable-stories-playwright/src/reporter.ts

package/skills/playwright-story-api/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: playwright-story-api
+description: >
+  Write BDD stories in Playwright using executable-stories-playwright.
+  Top-level exports with TestInfo: story.init(testInfo). Async steps with
+  fixtures ({ page }). Steps: given, when, then, and, but. Doc entries:
+  json, kv, code, table, link, section, mermaid, screenshot, note, tag.
+  Auto-And keyword conversion. Aliases: arrange, act, assert.
+type: core
+library: executable-stories-playwright
+library_version: "7.0.1"
+sources:
+  - "jagreehal/executable-stories:packages/executable-stories-playwright/src/story-api.ts"
+  - "jagreehal/executable-stories:apps/docs-site/src/content/docs/playwright/playwright-story-api.md"
+---
+
+# executable-stories-playwright — Story API
+
+## Setup
+
+```typescript
+import { test, expect } from "@playwright/test";
+import { story, given, when, then } from "executable-stories-playwright";
+
+test.describe("Login page", () => {
+  test("authenticates with valid credentials", async ({ page }, testInfo) => {
+    story.init(testInfo, { tags: ["auth"], ticket: "AUTH-42" });
+
+    given("the login page is loaded");
+    await page.goto("/login");
+
+    when("valid credentials are entered");
+    await page.fill("#email", "alice@example.com");
+    await page.fill("#password", "secret");
+    await page.click('button[type="submit"]');
+
+    then("the dashboard is shown");
+    await expect(page.locator("h1")).toHaveText("Dashboard");
+  });
+});
+```
+
+File naming: `*.story.spec.ts`.
+
+Playwright uses top-level step exports. `story.init(testInfo)` requires the `testInfo` parameter from the test callback.
+
+## Core Patterns
+
+### Top-level step exports with fixtures
+
+```typescript
+import { story, given, when, then, and, but } from "executable-stories-playwright";
+
+test("blocks suspended user login", async ({ page }, testInfo) => {
+  story.init(testInfo);
+
+  given("the user account exists");          // renders "Given"
+  given("the account is suspended");          // renders "And" (auto-converted)
+  when("the user submits valid credentials");
+  await page.fill("#email", "user@test.com");
+  await page.click("#submit");
+
+  then("the user sees an error message");
+  await expect(page.locator(".error")).toBeVisible();
+
+  but("the user is not logged in");           // renders "But" (always)
+  await expect(page).toHaveURL("/login");
+});
+```
+
+### Doc entries with screenshots
+
+```typescript
+test("checkout flow", async ({ page }, testInfo) => {
+  story.init(testInfo);
+
+  given("a cart with items");
+  story.json({ label: "Cart", value: { items: 3, total: 150 } });
+
+  when("the user completes checkout");
+  await page.click("#checkout");
+  await page.waitForURL("/confirmation");
+
+  then("the confirmation page is shown");
+  story.screenshot({ path: "screenshots/confirmation.png", alt: "Order confirmation" });
+  story.table({
+    label: "Order details",
+    columns: ["Item", "Qty", "Price"],
+    rows: [["Widget", "3", "$50"]],
+  });
+});
+```
+
+### Step wrappers with timing
+
+```typescript
+const response = await story.fn("When", "the API is called", async () => {
+  return page.request.get("/api/data");
+});
+
+await story.expect("the response is successful", async () => {
+  expect(response.status()).toBe(200);
+});
+```
+
+### Suite headings from test.describe
+
+```typescript
+test.describe("Authentication", () => {
+  test("valid login", async ({ page }, testInfo) => {
+    story.init(testInfo);
+    // Produces "## Authentication" heading in generated docs
+  });
+});
+```
+
+Suite path comes from `testInfo.titlePath`. Describe titles become `##` headings in generated docs.
+
+## Common Mistakes
+
+### CRITICAL Missing testInfo argument in story.init()
+
+Wrong:
+
+```typescript
+test("my test", async ({ page }) => {
+  story.init();
+  given("something");
+});
+```
+
+Correct:
+
+```typescript
+test("my test", async ({ page }, testInfo) => {
+  story.init(testInfo);
+  given("something");
+});
+```
+
+Without `testInfo`, story metadata is not linked to the test. The `testInfo` parameter must be the second argument in the Playwright test callback.
+
+Source: packages/executable-stories-playwright/src/story-api.ts
+
+### HIGH Using .story.test.ts file extension
+
+Wrong:
+
+```
+tests/login.story.test.ts
+```
+
+Correct:
+
+```
+tests/login.story.spec.ts
+```
+
+Playwright uses `.spec.ts` by convention. The reporter filters for `.story.spec.ts` files. Using `.test.ts` may cause the reporter to miss story metadata.
+
+Source: CLAUDE.md — "Story test files use .story.spec.ts (playwright)"
+
+### HIGH Forgetting testInfo in callback destructuring
+
+Wrong:
+
+```typescript
+test("my test", async ({ page }) => {
+  story.init(testInfo);  // testInfo is undefined
+});
+```
+
+Correct:
+
+```typescript
+test("my test", async ({ page }, testInfo) => {
+  story.init(testInfo);
+});
+```
+
+`testInfo` is the second parameter of the Playwright test callback, not a fixture. It must be explicitly named after the fixtures object.
+
+Source: packages/executable-stories-playwright/src/story-api.ts
+
+### MEDIUM Calling steps before story.init()
+
+Wrong:
+
+```typescript
+test("my test", async ({ page }, testInfo) => {
+  given("something");
+  story.init(testInfo);
+});
+```
+
+Correct:
+
+```typescript
+test("my test", async ({ page }, testInfo) => {
+  story.init(testInfo);
+  given("something");
+});
+```
+
+Steps called before `init()` are silently dropped because no story context exists.
+
+Source: packages/eslint-plugin-executable-stories-playwright/src/rules/require-story-context-for-steps.ts