Create Tests with Cursor / Claude Code

# Stably SDK — AI Rules (Playwright‑compatible)

**Assumption:** Full Playwright parity unless noted below.

## Import

```ts
import { test, expect } from "@stablyai/playwright-test";
```

## Install & Setup

```bash
npm remove playwright @playwright/test
npm install @stablyai/playwright-test
export STABLY_API_KEY=YOUR_KEY
```

```ts
import { setApiKey } from "@stablyai/playwright-test";
setApiKey("YOUR_KEY");
```

## Config (Auto‑Heal)

Create `stably.config.ts` next to `playwright.config.ts`.

```ts
import { defineStablyConfig } from "@stablyai/playwright-test";
export default defineStablyConfig({
  use: {
    autoHeal: {
      enabled: true,
      model: "claude-sonnet-4-5", // only supported model
      locators: { enabled: true, timeout: 30_000 },
      screenshots: { enabled: true },
    },
  },
});
```

* Disable globally via `autoHeal.enabled = false`.

## Auto‑Heal

* **Locator healing requires** `.describe()` on locators (encodes intent). On failure, AI finds alternatives and persists them in reporter artifacts.
* **Visual heal for** `expect(page).toHaveScreenshot(...)`: ignores benign render variance (fonts/subpixel).

```ts
await page.getByRole("button", { name: "Get Started" })
  .describe("CTA button").click();
await expect(page).toHaveScreenshot("dashboard.png");
```

## AI Assertions (intent‑based visuals)

```ts
await expect(page).toMatchScreenshotPrompt(
  "Shows revenue trend chart and spotlight card",
  { timeout: 30_000 }
);
await expect(page.locator(".header"))
  .toMatchScreenshotPrompt("Nav with avatar and bell icon");
```

**Signature:** `expect(page|locator).toMatchScreenshotPrompt(prompt: string, options?: ScreenshotOptions)`

* Use for **dynamic** UIs; keep prompts specific; scope with locators when possible.
* **Consider whether you need `fullPage: true`**: Ask yourself if the assertion requires content beyond the visible viewport (e.g., long scrollable lists, full page layout checks). If only viewport content matters, omit `fullPage: true` — it's faster and cheaper. Use it only when you genuinely need to capture content outside the browser window's visible area. 

## AI Extraction (visual → data)

```ts
const txt = await page.extract("List revenue, active users, and churn rate");
```

Typed with Zod:

```ts
import { z } from "zod";
const Metrics = z.object({ revenue: z.string(), activeUsers: z.number(), churnRate: z.number() });
const m = await page.extract("Return revenue (currency), active users, churn %", { schema: Metrics });
```

**Signatures:**

* `page.extract(prompt: string): Promise<string>`
* `page.extract<T extends z.AnyZodObject>(prompt, { schema: T }): Promise<z.output<T>>`

## CI Reporter / Cloud

```bash
npm install @stablyai/playwright-reporter
```

```ts
// playwright.config.ts
export default defineConfig({
  reporter: [["list"], ["@stablyai/playwright-reporter"]],
});
```

```bash
export STABLY_API_KEY=YOUR_TEAM_KEY
export STABLY_PROJECT_ID=YOUR_PROJECT_ID
```

## Commands

```bash
npx playwright test   # preferred to enable full auto‑heal path
# All Playwright CLI flags still work (headed, ui, project, file filters…)

# When running tests for debugging/getting stacktraces:
npx playwright test --reporter=list  # disable HTML reporter, shows terminal output directly
```

## Development Workflow

**Iterative Test Development:**
* You can **dynamically simulate test execution in the browser**, change tests accordingly, until the test passes
* When debugging failures, run `npx playwright test` with `--reporter=list` flag to disable the HTML reporter and get immediate stacktrace output in the terminal

## Maintenance Agents (regeneration)

Use when flows materially changed; suggested code edits appear in reporter artifacts. Prefer action‑level heal for small UI shifts.

## Best Practices

* Add `.describe()` to important locators; combine with `getByRole`/`getByTestId`.
* Stabilize before visuals (network/animation idle).
* Scope visual checks with locators; keep prompts specific with labels/units.
* Use `toHaveScreenshot` for stable pixel‑perfect UIs; `toMatchScreenshotPrompt` for dynamic UIs.
* **Be deliberate with `fullPage: true`**: Default to viewport-only screenshots. Only use `fullPage: true` when your assertion genuinely requires content beyond the visible viewport (e.g., verifying footer content on a long page, checking full scrollable lists). Viewport captures are faster and more cost-effective. 

## Troubleshooting

* **Flapping locator** → add `.describe()` + tighter scoping.
* **CI‑only diffs** → ensure fonts/GPU consistency; update baseline or mask.
* **Too much healing** → apply reporter’s suggested code updates.
* **Slow assertions** → scope visuals; reduce viewport.

## Notes & Limits

* Auto‑heal model: **`claude-sonnet-4-5` only** (locators & screenshots).
* Upcoming: `toMatchAriaPrompt`, prompt‑result caching, `context.agent(...)` autonomous workflows.

## Minimal Template

```ts
import { test, expect } from "@stablyai/playwright-test";

test("AI‑enhanced dashboard", async ({ page }) => {
  await page.goto("/dashboard");
  await page.getByRole("button", { name: "Get Started" })
    .describe("CTA button").click();
  await expect(page).toMatchScreenshotPrompt(
    "Dashboard shows revenue chart (>= 6 months) and account spotlight card"
  );
});
```