Skip to main content
Stably SDK is designed to be a drop-in replacement for Playwright test, providing 100% Playwright compatibility while using AI to make your Playwright tests more reliable and easier to maintain.

Installation & Setup

1

Setup API Key

Get a Team API Key from your Stably Dashboard and set it as an environment variable:
export STABLY_API_KEY=your_api_key_here
The tests will expect process.env.STABLY_API_KEY, but you can also programmatically set a key using the setApiKey function from @stablyai/playwright-test:
import { setApiKey } from "@stablyai/playwright-test";

setApiKey("your_api_key_here");
2

Install Playwright and Stably SDK

Stably SDK now supports bringing your own Playwright version. Install both:
npm install @playwright/test @stablyai/playwright-test
If you already have @playwright/test installed, you only need to add @stablyai/playwright-test. The SDK is compatible with Playwright 1.52.0+.

Usage

1. Update Your Code

Replace all imports from @playwright/test with @stablyai/playwright-test:
// Before
import { test, expect } from "@playwright/test";

// After
import { test, expect } from "@stablyai/playwright-test";
Example of replacing @playwright/test imports with @stablyai/playwright-test

2. Setup AI Rules (Optional)

Teach AI codegen agents (like Cursor, Claude Code, or Codex) how to properly use Stably SDK’s AI capabilities instead of writing basic Playwright code.
1

Copy the AI rules below

# 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 install @playwright/test @stablyai/playwright-test
export STABLY_API_KEY=YOUR_KEY
```

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


## 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-test
```

```ts
// playwright.config.ts
import { defineConfig } from "@playwright/test";
import { stablyReporter } from "@stablyai/playwright-test";

export default defineConfig({
  reporter: [
    ["list"],
    stablyReporter({ apiKey: process.env.STABLY_API_KEY, projectId: "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

## AI Agent (autonomous workflows)

Use the `agent` fixture to execute complex, multi-step workflows:

```ts
test("complex workflow", async ({ agent, page }) => {
  await page.goto("/orders");
  await agent.act("Find the first pending order and mark it as shipped", { page });
});

// Or create manually
const agent = context.newAgent();
await agent.act("Your task here", { page, maxCycles: 30 });
```

**Signature:** `agent.act(prompt: string, options: { page: Page, maxCycles?: number, model?: string }): Promise<{ success: boolean }>`

* Default maxCycles: 30
* Supported models: `anthropic/claude-sonnet-4-5-20250929` (default), `google/gemini-2.5-computer-use-preview-10-2025`

## 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

* **Slow assertions** → scope visuals; reduce viewport.
* **Agent stops early** → increase `maxCycles` or break task into smaller steps.

## Minimal Template

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

test("AI‑enhanced dashboard", async ({ page, agent }) => {
  await page.goto("/dashboard");
  
  // Use agent for complex workflows
  await agent.act("Navigate to settings and enable notifications", { page });
  
  // Use AI assertions for dynamic content
  await expect(page).toMatchScreenshotPrompt(
    "Dashboard shows revenue chart (>= 6 months) and account spotlight card"
  );
});
```
2

Paste into your AI codegen agent's configuration

Add the copied rules to your agent’s custom instructions (e.g., .cursorrules, .windsurfrules, claude.md, or any method that supports custom prompts).
3

Start using Stably SDK patterns

Your codegen agent now knows Stably SDK patterns: auto-heal with .describe(), toMatchScreenshotPrompt() for AI assertions, and extract() for data extraction.

3. Run Tests

Use the same Playwright commands you’re already familiar with:
npx playwright test
You can follow the same instructions from the Playwright documentation, including:
  • Run tests in headed mode: npx playwright test --headed
  • Run a specific test file: npx playwright test tests/example.spec.ts
  • Run tests in UI mode: npx playwright test --ui
  • Run a single project/browser: npx playwright test --project=chromium

4. Add Stably CI Reporter (Optional)

To integrate with Stably’s cloud platform and view test results in the dashboard, configure the reporter in your playwright.config.ts:
playwright.config.ts
import { defineConfig } from "@playwright/test";
import { stablyReporter } from "@stablyai/playwright-test";

export default defineConfig({
  reporter: [
    ["list"],
    stablyReporter({ apiKey: process.env.STABLY_API_KEY, projectId: "your_project_id_here" }), // Stably reporter
  ],
});
Set environment variables:
export STABLY_API_KEY=your_team_api_key_here
  • Get your Team API Key from Stably Dashboard
  • Find your Project ID in your project settings on the Stably Dashboard
  • The reporter is now included in @stablyai/playwright-test - no separate package needed!
Once configured, your test results will automatically sync to the Stably platform when tests run.

Prefer a no-code approach?

If you don’t want to manage Playwright configuration, runners, and maintenance yourself, you can use Stably’s no-code AI tests to get the same capabilities—AI test generation, AI assertions, AI actions, and auto-heal—running on our scalable cloud platform without writing code.
  • Same power, simpler UX: Built on top of Playwright, with a streamlined editor UI.
  • AI-first: Natural-language test generation, AI assertions, AI actions, and self-healing.
  • Cloud-native: Record, run, and triage at scale with zero local setup.
  • Portable: Export tests to Playwright anytime if you need advanced customization.

Quick start (no-code)

  1. Sign in to the Stably Dashboard: Open Dashboard.
  2. Create a project and open the recorder in the no-code editor.
  3. Record steps or use AI to generate them in the editor: see No-code Editor.
  4. Add intelligence to your test with AI Assertions and AI Actions.
  5. Run in the cloud and review results: see Viewing Run Results and Test Results.
The no-code editor is Playwright-compatible under the hood. You can export tests to Playwright at any time and continue in code when you need more advanced workflows. Learn more in Full Playwright Compatibility.