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

​
Installation & Setup

1

Remove existing Playwright (if installed)

If you already have Playwright installed:
cd your-e2e-tests-directory
npm remove playwright @playwright/test
2

Install Stably Playwright SDK

Navigate to your e2e tests directory (the one that previously had the @playwright/test dependency):
cd your-e2e-tests-directory
npm install @stablyai/playwright-test
3

Setup API Key

Get a Team API Key from your Stably Settings 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");

​
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. 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

​
3. Enable AI Auto-Heal (Optional)

To enable AI auto-heal capabilities, create a stably.config.ts file in the same folder as your playwright.config.ts:
Model support: Stably currently supports only claude-sonnet-4-5 for auto-heal functionality. This model has demonstrated the best accuracy and reliability for both locator and screenshot healing. We plan to expand support for additional models in the future.
stably.config.ts
import { defineStablyConfig } from '@stablyai/playwright-test';

// stably.config.ts
export default defineStablyConfig({
  use: {
    autoHeal: {
      // Global defaults
      enabled: true,
      model: 'claude-sonnet-4-5',
      
      // Locator-specific config
      locators: {
        // inherits global settings, can override
        enabled: true,
        model: 'some other model',
        timeout: 30000,
      },
      
      // Screenshot-specific config
      screenshots: {
        enabled: true,
        model: 'different model'
      },
    },
  },
});

​
4. Add Stably CI Reporter (Optional)

To integrate with Stably’s cloud platform and view test results in the dashboard:
1

Install the reporter package

npm install @stablyai/playwright-reporter
2

Configure the reporter

Add the Stably reporter to your playwright.config.ts:
playwright.config.ts
// Before
export default defineConfig({
  reporter: "list",
});

// After
export default defineConfig({
  reporter: [
    ["list"],
    ["@stablyai/playwright-reporter"], // Stably custom reporter
  ],
});
3

Set environment variables

Export the required environment variables:
export STABLY_API_KEY=your_team_api_key_here
export STABLY_PROJECT_ID=your_project_id_here
  • Get your Team API Key from Stably Settings
  • Find your Project ID in your project settings on the Stably Dashboard
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. Auto-healing is available out of the box: see Auto-Heal.
  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.
⌘I