SDK reference

Heal.init(options?)

Creates a Heal instance: launch a browser session, then returns a handle you use for getPage(), etc. Call once per test (or once per fixture scope), then close() when done.

static init(options?: HealOptions): Promise<Heal>;

HealOptions (all optional):

Creates a new Heal instance with an auto-healing browser context.

Heal instance methods

• getPage(): Returns { page, agent } with Heal's self-healing proxy.
• newPage(): Opens a new page in the browser context.
• getBrowserContext(): Returns the underlying Playwright BrowserContext.
• waitForNewPage(action, timeoutMS?): Waits for a new page to open as a result of an action.
• close(): Closes the browser and cleans up resources.

getPage()

Returns { page, agent } for Heal’s first browser tab. Call heal actions on agent, and optionally call page for regular playwright. Calling getPage() multiple times returns the same page and agent—use this at the start of a test when a single tab is enough.

getPage(): Promise<HealPageContext>;

Example

const { page, agent } = await heal.getPage();
await page.goto(entryUrl);
await agent.healClick('the login button');

newPage()

Opens a new tab in the same Playwright BrowserContext and returns a fresh { page, agent } pair. Use when you need an extra tab without closing the first (e.g. parallel UI or a clean navigation stack).

newPage(): Promise<HealPageContext>;

Example

const { page: tab1, agent: agent1 } = await heal.getPage();
const { page: tab2, agent: agent2 } = await heal.newPage();
await tab2.goto('https://example.com');
await agent2.healClick('submit');

getBrowserContext()

Returns the underlying Playwright BrowserContext. Use when you need low-level APIs (cookies, permissions, multiple pages without Heal’s agent, etc.). Prefer getPage() / newPage() / waitForNewPage() for normal Heal flows.

getBrowserContext(): BrowserContext;

Example

const context = heal.getBrowserContext();
const pages = context.pages();

waitForNewPage(action, timeoutMS?)

Runs an async action (typically one that opens a link in a new tab) and waits until a new page is created, then returns { page, agent } for that new tab. Use when the application opens the tab (e.g. “Download” or “Open in new window”), not when you want to open a tab yourself—in that case use newPage().

waitForNewPage(action: Promise<void>, timeoutMS?: number): Promise<HealPageContext>;

Example

const { page: pdfTab, agent: pdfAgent } = await heal.waitForNewPage(
  agent.healClick('Télécharger la fiche patient'),
);
await pdfAgent.healAssert('PDF viewer is visible');
await pdfTab.close();

close()

Closes the browser context and releases resources. Call once at the end of each test (e.g. in a fixture after hook or after the test body) so sessions do not leak.

close(): Promise<void>;

Example

const heal = await Heal.init({ headless: true, locale: 'fr-FR' });
try {
  const { page, agent } = await heal.getPage();
  // … test steps …
} finally {
  await heal.close();
}

Browser interactions

Browser interactions should be called on an HealPageAgent, as returned by getPage or newPage.

• agent.healClick(description): Click an element described in natural language.
• agent.healType(description, value): Type into an element described in natural language.
• agent.healSelectOption(description, option): Select an option from a dropdown described in natural language.
• agent.healHover(description): Hover over an element described in natural language.
• agent.healLocator(description): Returns a Playwright Locator for an element described in natural language.
• agent.healAssert(assertion): Assert a condition on the page described in natural language.
• agent.healScreenshot(): Takes a screenshot of the current page and returns it as a base64 string.

Supported Playwright features

Configuration (playwright.config.ts)

• testDir: root test directory
• projects: array of project configurations with name, testMatch, testDir, and dependencies
• Project dependency graph with cycle detection and topological ordering

Test patterns

• test() and it() declarations
• test.describe() with nesting
• test.afterEach() (scope-aware)
• Custom fixtures via base.extend() — function-style, array-style with { auto: true }, and { option: true }
• Fixture teardown via use() boundary detection
• Fixture dependency resolution and topological sorting
• test.use() overrides (scope-aware within describe blocks)
• Built-in fixtures auto-provided when needed: page, context, browser, request

Test file extensions

*.spec.ts, *.spec.js, *.test.ts, *.test.js, *.spec.tsx, *.spec.jsx, *.test.tsx, *.test.jsx

Code patterns

• Control flow blocks (if/else, for, while, try/catch, switch) treated as atomic executable units
• File-level and describe-block-level variable declarations
• Import statements preserved for execution context

Blocks (reusable helper functions)

• import * as blocks from './blocks' pattern
• Automatic inlining of await blocks.functionName(...) calls
• Parameter binding, return value capture, and setup/teardown support

Related pages

• Overview and examples: SDK overview
• Edge cases and gaps: Known limitations