Welcome to Stably Playwright SDK Setup!

I'll guide you through the 9-step installation process.

**Then automatically:**

Search the project comprehensively for:
1. ALL directories containing test files - use pattern matching:
    - Find all *.test.ts, *.spec.ts, *.test.js, *.spec.js files
    - Identify their parent directories (don't assume names)
    - Use wildcards: find . -name "*test*" -type d or find . -name "*e2e*" -type d
2. Check playwright.config.ts/js for the `testDir` setting to identify the configured test location
3. Check if `@playwright/test` is already in `package.json` dependencies
4. List ALL test directories found

Report findings:

---

undefined

**Then automatically:**

Look in `package.json` for `@playwright/test`:

**If Playwright is already installed:**
- Check the version (must be 1.52.0+)
- If version >= 1.52.0, report: `I see you have Playwright ${version} installed. This is compatible with Stably SDK.`
- **If version < 1.52.0, STOP and ask:**

**WAIT for confirmation before upgrading.**

**If Playwright is NOT installed:**
- Detect the package manager (check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`/`npm-shrinkwrap.json`)
- Navigate to the test directory (or project root) and run:
```bash

**After completing, announce:**

---

undefined

**Then automatically:**

Check if `@stablyai/playwright-test` exists in `package.json`:

**If already installed:**
- Check the version
- Automatically upgrade to latest: `npm install -D @stablyai/playwright-test@latest` (or equivalent)

**If not installed:**
- Use the detected package manager to install:
```bash

**After installing the core SDK, ask about email testing:**

**If yes**, install with the detected package manager:
```bash

**If pnpm shows a store location error:**
- Stop and explain to the user:

- **WAIT for confirmation**
- Only if user confirms, run `pnpm install` (without -y flag, let pnpm prompt naturally)
- After successful reinstall, retry: `pnpm add -D @stablyai/playwright-test@latest`

After successful installation:

**Verify and fix package.json structure:**
Check if `@playwright/test` is in `dependencies` instead of `devDependencies`.

**If found in wrong location:**
- Automatically move it and inform:

**After completing, announce:**

---

undefined

**Then automatically:**

Find all test files that import from `@playwright/test`:

1. Do a comprehensive project-wide search:
```bash
find . -type f \( -name "*.spec.ts" -o -name "*.test.ts" -o -name "*.spec.js" -o -name "*.test.js" \) -not -path "*/node_modules/*" -exec grep -l "@playwright/test" {} \;

I found ${count} test files that need import updates:
- tests/example.spec.ts
- tests/login.spec.ts
...

I'll update them all at once using this command:
find <test_directory> -name "*.spec.ts" -o -name "*.spec.js" -o -name "*.test.ts" -o -name "*.test.js" | xargs sed -i '' "s/@playwright\/test/@stablyai\/playwright-test/g"

This will replace all @playwright/test imports with @stablyai/playwright-test.

May I proceed with the bulk update?

Updated imports in ${count} test files
Verified: All test files now import from @stablyai/playwright-test

Step 4 Complete: Test file imports updated

Proceeding to Step 5...

undefined

**Then automatically:**

<!-- ── Stably Playwright SDK ────────────────────────────────── -->

If the file already contains a `<!-- ── Stably Playwright SDK` section, **replace** it instead of appending.

Step 5 Complete: AI rules configured

Files created/updated:
- claude.md (in <location>) — Claude Code knows Stably SDK capabilities
  and will load the full reference via /stably-sdk-rules when writing tests
- agents.md (in <location>) — Same rules for other AI agents
- .cursor/rules/stably-sdk-rules.mdc — Full Cursor rules (if applicable)
- .cursor/commands/create-e2e-test.md — Cursor command (if applicable)

Proceeding to Step 6...

undefined

**Then automatically:**

Find `playwright.config.ts`, `playwright.config.js`, or `playwright.config.mjs`.

import { defineConfig, stablyReporter } from '@stablyai/playwright-test';
import { devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['list'],
    stablyReporter({
      apiKey: process.env.STABLY_API_KEY,
      projectId: process.env.STABLY_PROJECT_ID,
    }),
  ],
  use: {
    trace: 'on',
    screenshot: 'on',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

Step 6 Complete: playwright.config.ts updated

Key changes:
- defineConfig now imported from @stablyai/playwright-test
- stablyReporter added to reporter array
- Tracing enabled (required for Stably trace uploads)

Credentials are read from STABLY_API_KEY and STABLY_PROJECT_ID env vars.
We'll set those up in the next step.

Proceeding to Step 7...

undefined

**WAIT for user's choice, then proceed based on their answer:**

**If they choose Option 1 (Guide me to set up .env file):**
Provide instructions:

**WAIT for user to confirm they've added the credentials.**

**If they choose Option 2 (Already configured):**

**If they choose Option 3 (Other secret management):**
Ask the user to describe their setup:

**WAIT for user's description, then:**
- Acknowledge their setup and confirm that playwright.config is already configured to use `process.env.STABLY_API_KEY` and `process.env.STABLY_PROJECT_ID`
- Provide any relevant guidance for their specific setup
- Proceed to Step 8

**Important: Never read or write .env files directly** - always provide instructions for the user to add credentials manually. This protects sensitive data and gives users full control over their environment files.

**After completing credentials setup, announce:**

---

undefined

**WAIT for user's decision (yes/no/skip).**

**If yes:**
Run package-manager-appropriate command:
- npm: `npm install -g @playwright/mcp`
- pnpm: `pnpm add -g @playwright/mcp`
- yarn classic: `yarn global add @playwright/mcp`
- yarn berry: `yarn dlx @playwright/mcp --help` (no global add)

**After completing or skipping, announce:**

---

undefined

**WAIT for user confirmation.**

**If yes:**

1. Create `${test_directory}/stably-verification.spec.ts`:
```typescript
import { test, expect } from '@stablyai/playwright-test';

test('stably sdk verification', async ({ page }) => {
    await page.goto('https://www.stably.ai');
    await expect(page).aiAssert("the page shows the Stably home page");
});

Stably Playwright SDK Setup Complete!

Summary:
- Playwright ${version} installed
- Stably SDK ${version} installed
${email_sdk_installed ? '- Stably Email SDK installed' : ''}
- ${count} test files updated
- AI rules configured for ${ide_name}
- Playwright config updated with Stably reporter
- API credentials configured
${mcp_installed ? '- Playwright MCP installed' : ''}

Next steps:
1. Run your tests with your package manager (`npm exec playwright test`, `pnpm exec playwright test`, or `yarn playwright test`)
2. View results in Stably Dashboard: https://app.stably.ai
3. Check out the docs: https://docs.stably.ai

Happy testing!