SDK overview

What the Heal SDK is

Heal is an SDK that allows you to write stable end-to-end tests using natural language on top of Playwright. Because Heal runs your tests through Playwright, you retain the full power of the Playwright engine while gaining a higher-level, intent-based API for interactions and assertions.

Drop‑in replacement for Playwright actions

Heal SDK calls are designed to be a drop‑in replacement for many playwright actions. Instead of using locators, you describe the element's intent.

// Finding the row with "John Doe" and clicking the Edit button inside it
const userRow = page.locator('tr', { hasText: 'John Doe' });
await userRow.getByRole('button', { name: 'Edit' }).click();

// Filling a specific field in a modal that just appeared
await page.getByLabel('Job Title').fill('Senior Engineer');
await page.getByRole('button', { name: 'Save Changes' }).click();

with Heal you can instead write:

// Heal understands the visual and semantic context automatically
await agent.healClick('the Edit button for John Doe');

// Heal can handle descriptive input targets
await agent.healType(
  'the Job Title field in the edit modal',
  'Senior Engineer',
);
await agent.healClick('the Save button');

The rest of your test structure — fixtures, configuration, test runner setup — can remain the same.

Caching

Under the hood, heal grounds elements and dynamically find stable locators to cache. LLMs are called only when locators break, which makes Heal more stable, faster and token-efficient

Mix and match

You can mix and match playwright and heal calls. Heal gives you accept to the playwright page object, as well as an agent object to call heal methods.

const { page, agent } = await heal.getPage();

// A Heal call
await healAgent.leftClick(
  'The contact doctor button in the first card on the left',
);

// A playwright expect
await expect(page).toHaveURL(/doctor/);

This means you can:

• Adopt Heal gradually in specific flows or files.
• Keep using existing Playwright helpers, fixtures, and plugins.
• Reach for raw Playwright whenever you need low-level control.

For full API details and supported patterns, see the SDK reference.

Next steps

• Deep dive into the API surface in the SDK reference.
• Review edge cases and gaps in Known limitations.