Skip to main content
Stably SDK is the engine behind both Stably CLI and Stably Web Editor — the same Playwright-compatible runtime executes your tests in code and no-code workflows.
Stably is 100% Playwright-compatible: keep your playwright.config.*, fixtures, locators, and CLI habits while layering in AI assertions, actions, and self-healing.
Stably SDK extends the Playwright test runner with AI capabilities while keeping your existing tests, fixtures, and configuration intact. Use it as a drop-in import to gain AI assertions, AI actions, and self-healing without rewriting your suite.

​
Keep Playwright, Add Stably

  • Works with your current playwright.config.*, fixtures, and expect matchers
  • Supports standard commands like npx playwright test; use npx stably test to enable auto-heal and richer triage
  • No breaking changes to page interactions, locators, or custom utilities
import { test, expect, agent } from '@stablyai/playwright-test';

test('UI flows stay Playwright-compatible', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page.locator('text=Success')).toBeVisible();

  // AI add-ons
  await expect(page).toMatchScreenshotPrompt('Shows a success state with a green confirmation banner');
  await agent.act('Open the first pending request and approve it', { page });
});

​
AI Capabilities at a Glance

  • AI-powered assertions: Intent-based visual checks with toMatchScreenshotPrompt.
  • Agent actions: Natural-language flows that handle multi-step UI work.
  • Auto-maintenance: Keeps locators stable and reduces flakes as your app evolves.

​
Call the Stably API Directly

Use the Stably REST API when you need to trigger runs, poll status, or pull results without invoking the Playwright runner directly. Authentication uses a Bearer token—see the API key dashboard and the API reference for required headers and full endpoint details. 
// node-fetch is used for portability; replace with your preferred HTTP client.
import fetch from 'node-fetch';

async function runSuiteViaApi(testSuiteId: string) {
  const apiKey = process.env.STABLY_API_KEY;
  if (!apiKey) throw new Error('Set STABLY_API_KEY before calling the API.');

  const trigger = await fetch(`https://api.stably.ai/v1/testSuite/${testSuiteId}/run`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${apiKey}` }
  });
  if (!trigger.ok) {
    const error = await trigger.text();
    throw new Error(`Failed to start suite ${testSuiteId}: ${trigger.status} ${error}`);
  }
  const { testSuiteRunId } = await trigger.json();

  const status = await fetch(`https://api.stably.ai/v1/testSuiteRun/${testSuiteRunId}/status`, {
    headers: { Authorization: `Bearer ${apiKey}` }
  });
  if (!status.ok) {
    const error = await status.text();
    throw new Error(`Failed to read status for ${testSuiteRunId}: ${status.status} ${error}`);
  }
  const { status: runStatus, results } = await status.json();
  console.log(`Run ${testSuiteRunId} is ${runStatus}`);
  console.log('Results summary:', results);
}

runSuiteViaApi('ts_123').catch((err) => {
  console.error('API invocation failed', err);
});

​
Getting Started

Follow the SDK Setup Guide to install the package, swap in the Stably runner import, and enable AI features.

​
Adopt Gradually

  • Start by running existing tests with the Stably import to validate compatibility.
  • Migrate critical journeys first, then layer on AI assertions and actions where they reduce flaky maintenance.
  • Keep your preferred Playwright versioning and tooling; Stably fits into your current CI, CLI, and editor workflows.