Skip to main content
Stably SDK is designed to be a drop-in extension for Playwright, providing 100% Playwright 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');
});

​
Perform complex actions with AI

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

​
Integration Steps

1

Install Playwright and Stably SDK

Stably SDK now supports bringing your own Playwright version. Install both:
cd your-e2e-tests-directory
npm install @playwright/test @stablyai/playwright-test
2

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");
3

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';
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({ 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 Settings
  • 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!

​
Performance Benefits

  • Automatic maintenance of test suites via our auto-maintenance agents
  • Flexible version control - choose your preferred Playwright version

​
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 extension, so any issues are likely configuration-related rather than API incompatibilities.