claude-toolkit 0.1.12 → 0.1.20

package/stacks/playwright/skills/ct-playwright-patterns/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: ct-playwright-patterns
+description: Playwright E2E testing patterns -- Page Objects, fixtures, auth, network mocking, and CI/CD
+---
+
+# Playwright E2E Patterns
+
+E2E tests sit at the top of the testing pyramid. They exercise full user journeys in real browsers. Write fewer, make each one count.
+
+## Project Structure
+
+```
+e2e/
+  fixtures/          # Custom Playwright fixtures
+    index.ts         # Extended test with page objects
+  pages/             # Page Object classes
+  components/        # Component Object classes (reusable fragments)
+  specs/             # Test files organized by feature
+  helpers/           # Utilities (data factories, API helpers)
+  .auth/             # storageState files (gitignored)
+```
+
+## Page Object Model + Fixtures
+
+Combine Page Objects with custom fixtures. Tests receive pre-built page objects:
+
+```typescript
+// e2e/pages/LoginPage.ts
+export class LoginPage {
+  private readonly emailInput: Locator;
+  private readonly submitButton: Locator;
+
+  constructor(private readonly page: Page) {
+    this.emailInput = page.getByLabel("Email");
+    this.submitButton = page.getByRole("button", { name: "Sign in" });
+  }
+
+  async goto() { await this.page.goto("/login"); }
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.submitButton.click();
+  }
+}
+
+// e2e/fixtures/index.ts
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => { await use(new LoginPage(page)); },
+});
+```
+
+Fixtures are lazy (created on demand) and composable (can depend on each other).
+
+## Authentication
+
+Use project dependencies with `storageState` to authenticate once and reuse:
+
+```typescript
+// e2e/auth.setup.ts
+setup("authenticate", async ({ page }) => {
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("test@example.com");
+  await page.getByRole("button", { name: "Sign in" }).click();
+  await page.waitForURL("/dashboard");
+  await page.context().storageState({ path: "e2e/.auth/user.json" });
+});
+```
+
+Config: `dependencies: ["setup"]` + `storageState: "e2e/.auth/user.json"`. Add `e2e/.auth/` to `.gitignore`.
+
+For multi-role testing, create separate setup files per role.
+
+## Locator Priority
+
+1. `getByRole()` -- accessibility semantics, survives refactors
+2. `getByLabel()` -- form elements
+3. `getByPlaceholder()` -- input hints
+4. `getByText()` -- visible text
+5. `getByTestId()` -- stable but less semantic
+6. CSS/XPath -- **avoid**
+
+## Web-First Assertions
+
+Always use auto-retrying assertions:
+
+```typescript
+// GOOD
+await expect(page.getByRole("alert")).toBeVisible();
+await expect(page).toHaveURL("/dashboard");
+
+// BAD -- checks once, no retry
+expect(await page.getByRole("alert").isVisible()).toBeTruthy();
+```
+
+Key assertions: `toBeVisible()`, `toBeEnabled()`, `toHaveText()`, `toHaveURL()`, `toHaveCount()`, `toHaveScreenshot()`, `toMatchAriaSnapshot()`.
+
+## Network Mocking
+
+```typescript
+// Mock API
+await page.route("**/api/users", async (route) => {
+  await route.fulfill({ status: 200, contentType: "application/json", body: JSON.stringify([{ name: "Alice" }]) });
+});
+
+// Block analytics
+await page.route("**/analytics/**", (route) => route.abort());
+```
+
+Mock ~80% of API calls for speed; keep ~20% hitting real endpoints. Always call `route.continue()`, `route.fulfill()`, or `route.abort()`. Use `page.unrouteAll()` in cleanup.
+
+## WebSocket Mocking (v1.53+)
+
+```typescript
+await page.routeWebSocket("wss://example.com/ws", (ws) => {
+  ws.onMessage((message) => { ws.send("mocked response"); });
+});
+```
+
+## Accessibility Testing
+
+```typescript
+import AxeBuilder from "@axe-core/playwright";
+
+test("WCAG 2.1 AA", async ({ page }) => {
+  await page.goto("/");
+  const results = await new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21aa"]).analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+Aria snapshots (v1.52+): `await expect(nav).toMatchAriaSnapshot(...)`.
+
+## Parallelization
+
+- File-level parallel (default) -- start here
+- In-file: `test.describe.configure({ mode: "parallel" })`
+- Full: `fullyParallel: true` in config
+
+Each worker gets its own `BrowserContext` (isolated cookies/storage). Use `mode: "serial"` sparingly.
+
+## CI/CD
+
+- Use official Playwright Docker image (`mcr.microsoft.com/playwright:v1.58.0-noble`)
+- Upload reports + traces as artifacts
+- Use `--shard` for suites exceeding 5 minutes
+- `retries: process.env.CI ? 2 : 0`
+- Traces: `trace: "on-first-retry"`
+
+## Flaky Test Prevention
+
+| Cause | Fix |
+|---|---|
+| `waitForTimeout()` | Web-first assertions or `waitForResponse` |
+| Brittle selectors | `getByRole`, `getByLabel`, `getByTestId` |
+| Shared state | Fresh `BrowserContext` per test |
+| External API flakiness | Mock with `page.route()` |
+| Animation timing | `--force-prefers-reduced-motion` |
+| Missing `await` | #1 source of false-passing tests. Lint for it. |
+
+## Anti-Patterns
+
+1. **Using `waitForTimeout()`** -- Use web-first assertions or explicit wait conditions.
+2. **Fragile CSS/XPath selectors** -- Use role-based and semantic locators.
+3. **Using `{ force: true }`** -- Masks real actionability problems.
+4. **Missing `await` on assertions** -- #1 source of false-passing tests.
+5. **Tests without assertions** -- A test that clicks without asserting is just a script.
+6. **Using Playwright for unit tests** -- Use Vitest for pure logic.
+7. **Committing raw codegen output** -- Always refactor into Page Objects.
+8. **Not cleaning up route handlers** -- Use `page.unrouteAll()`.

package/stacks/playwright/stack.json

@@ -0,0 +1,39 @@
+{
+	"name": "ct-playwright-patterns",
+	"description": "Playwright E2E testing patterns with Page Objects, fixtures, and CI/CD",
+	"defaultMappings": {
+		"e2e": "ct-playwright-patterns",
+		"playwright.config.ts": "ct-playwright-patterns"
+	},
+	"fileExtensions": ["spec.ts"],
+	"skillRules": {
+		"ct-playwright-patterns": {
+			"description": "Playwright E2E testing with Page Objects, fixtures, auth, and network mocking",
+			"priority": 7,
+			"triggers": {
+				"keywords": [
+					"playwright",
+					"e2e",
+					"end-to-end",
+					"page object",
+					"browser test",
+					"storageState"
+				],
+				"keywordPatterns": ["\\bplaywright\\b", "\\be2e\\b", "\\bpage\\s*object\\b"],
+				"pathPatterns": ["**/e2e/**", "**/*.spec.ts", "**/playwright.config.*"],
+				"intentPatterns": [
+					"(?:create|write|add).*(?:e2e|end.to.end|playwright).*(?:test)",
+					"(?:page object|fixture|browser test)"
+				],
+				"contentPatterns": [
+					"@playwright/test",
+					"page.goto",
+					"page.getByRole",
+					"storageState",
+					"base.extend"
+				]
+			},
+			"relatedSkills": ["ct-storybook-patterns", "ct-testing-patterns", "ct-vite-vitest-patterns"]
+		}
+	}
+}

package/stacks/solidjs/stack.json

@@ -46,7 +46,13 @@
 					"<Switch"
 				]
 			},
-			"relatedSkills": ["ct-vanilla-extract-patterns", "ct-testing-patterns"]
+			"relatedSkills": [
+				"ct-vanilla-extract-patterns",
+				"ct-testing-patterns",
+				"ct-vite-vitest-patterns",
+				"ct-storybook-patterns",
+				"ct-playwright-patterns"
+			]
 		}
 	}
 }

package/stacks/storybook/skills/ct-storybook-patterns/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: ct-storybook-patterns
+description: Storybook interaction testing, CSF 3 stories, play functions, a11y, and visual regression for SolidJS components
+---
+
+# Storybook Patterns
+
+Storybook is the middle layer of the testing pyramid: component interaction testing, visual regression, and accessibility auditing in a real browser.
+
+## SolidJS Integration
+
+Uses community packages: `storybook-solidjs` (renderer) + `storybook-solidjs-vite` (builder).
+
+**Critical:** Always use `createJSXDecorator` for JSX decorators. Standard decorators cause duplicate DOM elements with SolidJS.
+
+```tsx
+import { createJSXDecorator } from "storybook-solidjs";
+
+const ThemeDecorator = createJSXDecorator((Story) => (
+  <ThemeProvider><Story /></ThemeProvider>
+));
+```
+
+## CSF 3 Stories
+
+Use CSF 3 (not CSF Factories -- React-only as of Storybook 10.3).
+
+```tsx
+import type { Meta, StoryObj } from "storybook-solidjs";
+
+const meta = {
+  title: "Components/Button",
+  component: Button,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: { variant: "primary", children: "Click me" },
+};
+```
+
+### Coverage Checklist
+
+Every component needs stories for: all visual states (default, hover, focus, active, disabled, loading, error, empty), viewport sizes where layout differs, theme variants, edge cases (long text, missing data).
+
+## Interaction Testing
+
+Import everything from `@storybook/test` (instrumented versions). Never import from `@testing-library/dom` directly.
+
+```tsx
+import { expect, fn, userEvent, within } from "@storybook/test";
+
+export const SubmitForm: Story = {
+  args: { onSubmit: fn() },
+  play: async ({ canvasElement, args, step }) => {
+    const canvas = within(canvasElement);
+    await step("Fill form", async () => {
+      await userEvent.type(canvas.getByLabelText("Email"), "user@example.com");
+    });
+    await step("Submit", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "Sign in" }));
+    });
+    await expect(args.onSubmit).toHaveBeenCalledOnce();
+  },
+};
+```
+
+**Key rules:**
+1. Always `await` expect calls (enables Interactions panel logging).
+2. Use `step()` to organize complex interactions.
+3. Use `fn()` for spying (auto-restored between stories).
+
+## Running in CI (Vitest Addon)
+
+Use `@storybook/addon-vitest` (replaces old test-runner). No running Storybook instance needed.
+
+Required dependencies: `@storybook/addon-vitest`, `@vitest/browser`, `@vitest/browser-playwright`, `@vitest/coverage-v8`.
+
+Add as an inline project in your main Vite config using `test.projects`:
+
+```typescript
+// vite.config.ts
+import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
+import { playwright } from "@vitest/browser-playwright";
+
+export default defineConfig({
+  plugins: [/* ...app plugins */],
+  test: {
+    projects: [
+      {
+        extends: true,
+        test: { name: "unit", environment: "jsdom", setupFiles: ["./tests/setup.ts"] },
+      },
+      {
+        extends: true,
+        plugins: [storybookTest({ configDir: ".storybook" })],
+        test: {
+          name: "storybook",
+          browser: { enabled: true, headless: true, provider: playwright(), instances: [{ browser: "chromium" }] },
+          setupFiles: [".storybook/vitest.setup.ts"],
+        },
+      },
+    ],
+  },
+});
+```
+
+## Accessibility
+
+Built on axe-core. Set globally in `.storybook/preview.ts`:
+
+```typescript
+export default {
+  parameters: { a11y: { test: "error" } }, // "error" | "todo" | "off"
+  tags: ["a11y-test"],
+};
+```
+
+## MSW for API Components
+
+```typescript
+// .storybook/preview.ts
+import { initialize, mswLoader } from "msw-storybook-addon";
+initialize();
+export default { loaders: [mswLoader] };
+```
+
+Per-story handlers via `parameters.msw.handlers`. Keep success handlers in shared `mocks/handlers.ts`, override with error/edge-case at story level.
+
+## Module Mocking (Storybook 10)
+
+`sb.mock` for internal module replacement. Register in `.storybook/preview.ts` only:
+
+```typescript
+import { sb } from "@storybook/test";
+sb.mock("../src/api/client", () => ({ fetchUser: async () => ({ name: "Mock" }) }));
+```
+
+MSW for network-level; `sb.mock` for internal modules.
+
+## Portable Stories
+
+Reuse stories in Vitest with `composeStories`:
+
+```tsx
+import { composeStories } from "storybook-solidjs";
+import * as stories from "./Button.stories";
+const { Primary } = composeStories(stories);
+
+test("renders primary", () => {
+  const { getByRole } = render(() => <Primary />);
+  expect(getByRole("button")).toBeInTheDocument();
+});
+```
+
+## Anti-Patterns
+
+1. **Destructuring SolidJS props in stories** -- Pass props via `args`; use `createJSXDecorator` for decorators.
+2. **Importing from `@testing-library/dom`** -- Use `@storybook/test` for instrumented versions.
+3. **Not awaiting `expect()` in play functions** -- Always `await expect(...)`.
+4. **Skipping error/edge-case stories** -- Always include loading, error, empty, boundary states.
+5. **Using `@storybook/test-runner`** -- Use `@storybook/addon-vitest` instead.
+6. **Registering `sb.mock` in story files** -- Register in `.storybook/preview.ts` only.

package/stacks/storybook/stack.json

@@ -0,0 +1,46 @@
+{
+	"name": "ct-storybook-patterns",
+	"description": "Storybook interaction testing, CSF 3 stories, and visual regression for SolidJS",
+	"defaultMappings": {
+		".storybook": "ct-storybook-patterns",
+		"src/**/*.stories.tsx": "ct-storybook-patterns"
+	},
+	"fileExtensions": ["stories.tsx", "stories.ts"],
+	"skillRules": {
+		"ct-storybook-patterns": {
+			"description": "Storybook CSF 3 stories, play functions, a11y testing, and visual regression",
+			"priority": 7,
+			"triggers": {
+				"keywords": [
+					"storybook",
+					"story",
+					"stories",
+					"csf",
+					"play function",
+					"interaction test",
+					"visual regression",
+					"chromatic"
+				],
+				"keywordPatterns": ["\\bstorybook\\b", "\\bstories\\b", "\\bplay\\s+function\\b"],
+				"pathPatterns": ["**/*.stories.tsx", "**/*.stories.ts", "**/.storybook/**"],
+				"intentPatterns": [
+					"(?:create|write|add).*(?:story|stories|storybook)",
+					"(?:interaction|visual|a11y).*(?:test|testing)"
+				],
+				"contentPatterns": [
+					"satisfies Meta",
+					"StoryObj",
+					"@storybook/test",
+					"createJSXDecorator",
+					"storybook-solidjs"
+				]
+			},
+			"relatedSkills": [
+				"ct-solidjs-patterns",
+				"ct-testing-patterns",
+				"ct-vite-vitest-patterns",
+				"ct-playwright-patterns"
+			]
+		}
+	}
+}