Skip to main content
Stably SDK is designed to be a drop-in replacement for Playwright, providing 100% API compatibility while adding powerful AI-powered testing features. This means you can add Stably SDK to your Playwright tests with a few lines of code.

​
Seamless Integration

​
Existing Playwright Code Works Unchanged

Your existing Playwright tests work out of the box with Stably SDK: 
import { test, expect } from '@stablyai/playwright-test';

test('basic test', async ({ page }) => {
  await page.goto('https://example.com');
  await page.click('button');
  await expect(page.locator('text=Success')).toBeVisible();
});

​
Zero Breaking Changes

All Playwright APIs are fully supported:
  • Page interactions: click(), fill(), selectOption(), etc.
  • Assertions: All expect matchers work identically
  • Configuration: playwright.config.ts files work unchanged
  • Test runners: npx playwright test commands work the same, though we recommend using npx stably test command for additional auto-healing capabilities
  • Fixtures: Custom fixtures and page objects work unchanged

​
Enhanced Capabilities with AI

While maintaining full compatibility, Stably SDK adds AI-powered features:

​
AI-Powered Assertions

import { test, expect } from '@stablyai/playwright-test';

test('AI-powered assertions', async ({ page }) => {
  await page.goto('https://example.com');

  // Traditional assertion (still works)
  await expect(page.locator('.success-message')).toBeVisible();

  // Stably's AI-powered visual assertion
  await expect(page).toMatchScreenshotPrompt('There is a graph for recent sales numbers. All numbers should be above 60');
});

​
Self-Healing Tests

Tests automatically adapt to UI changes: 
// Before: Test fails when button text changes
await page.click('text=Start Now', describe: 'CTA button');

// After: Stably's test runner finds button even if text changes
await page.click('text=Get Started', describe: 'CTA button'); // AI finds the right element

​
Perform complex actions with AI

// Stably's AI agent understands natural language instructions
await context.agent.act('If you see a table with entries, delete the entries in the table until it is empty');
await context.agent.act('Remember the first entry in the table, now click into it and verify its content matches its table row');

​
Integration Steps

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@^0.1.2
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");
4

Update Imports

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';
5

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';

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,
        timeout: 30000,
      },
      
      // Screenshot-specific config
      screenshots: {
        enabled: true,
      },
    },
  },
});
6

Add Stably CI Reporter (Optional)

To integrate with Stably’s cloud platform and view test results in the dashboard:Install the reporter package:
npm install @stablyai/playwright-reporter
Configure the reporter in 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
  ],
});
Set 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

​
Performance Benefits

  • Reduced flakiness with self-healing capabilities
  • Better debugging with AI-generated test insights
  • Automatic maintenance of test suites via our auto-maintainance agents

​
Gradual Migration

Start by migrating one test at a time: 
import { test, expect } from '@stablyai/playwright-test';

// Keep old tests working
test('legacy test', async ({ page }) => {
  // ... existing code
});

// New tests with AI features
test('AI-enhanced test', async ({ page }) => {
  // ... AI-powered code
});

​
Support

If you encounter any compatibility issues during migration, our support team is here to help. Stably SDK is designed to be a true drop-in replacement, so any issues are likely configuration-related rather than API incompatibilities.
⌘I