DOCSEARCHbyAlgolia
Submit Docs

Heal Documentation

website·Indexed 33 days ago

https://docs.heal.dev

A CLI-first AI agent that writes, runs, and fixes Playwright tests. Heal provides a self-healing, AI-assisted test runner, an autopilot for test generation, an MCP server for browser validation loops, and an optional SDK for email and SMS utilities.

Tokens
7K
Snippets
39
Records
60
Agent score
54%

What's inside Heal

  1. Overview of Heal SDK email utilities

    The Heal SDK provides server-side helpers to test email flows such as sign-up confirmations, magic-link logins, and password resets. These methods poll for emails via the Heal proxy with a default timeout of 5 minutes. Each organization is assigned a dedicated email namespace: *.<org-slug>@tester-heal.dev. Any address following this pattern is valid and routable. The organization slug can be found in the Organisation tab of the Heal dashboard.

  2. Use the Heal MCP server for browser validation and test generation

    The heal MCP server exposes Autopilot functionality, enabling agents to run browser validation loops and generate Playwright tests without calling the CLI directly. It supports two primary modes:

    • build: Used to create or edit Playwright .test.ts files.
    • navigate: Used to drive the browser and validate behavior without writing a test file (equivalent to the CLI --navigation-mode).

  4. Understand the Heal SDK and its relationship with Playwright

    The Heal SDK allows developers to write stable end-to-end tests using natural language while leveraging the Playwright engine. It provides a higher-level, intent-based API for interactions and assertions. While Heal's default flow is CLI-first (generating regular Playwright code), the SDK is used for non-deterministic workflows where deterministic Playwright steps are impractical. To optimize performance and cost, Heal caches stable locators and only invokes LLMs when locators break.

  5. Implement an SMS verification flow in a test

    This example demonstrates how to use Heal.readSMS to automate a phone verification flow: capturing the current time, triggering the SMS, reading the resulting code, and entering it into the application.
    import { Heal } from '@heal-dev/sdk';

test('user can verify their phone number', async () => {
  const heal = await Heal.init({ headless: true });

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

    await page.goto('https://app.example.com/verify-phone');
    await agent.healType('the phone number field', '+14155552671');

    // Capture timestamp before triggering the SMS to avoid stale messages
    const since = new Date();
    await agent.healClick('the Send code button');

    // Poll for the SMS body
    const code = await Heal.readSMS('+14155552671', since);
    
    await agent.healType('the verification code field', code);
    await agent.healClick('the Verify button');
    await agent.healAssert('phone number is verified');
  } finally {
    await heal.close();
  }
});

  6. Use Heal in an agentic development loop with Claude

    Heal can be integrated into an agentic development loop to automatically validate work. In this mode, Heal drives the browser directly to validate behavior and provides feedback upon completion, but it does not generate Playwright code or test files. This approach is reported to be 2x faster and 2x more token-efficient than using playwright-cli with a State-of-the-Art (SoTA) model, with better handling of captions, SVGs, and complex interactions.
    # 1. Install Heal CLI
npm i -g @heal-dev/heal-cli

# 2. Authenticate
heal login

# 3. Install the necessary skill
npx heal skills install

# 4. Example prompt for Claude to trigger validation
claude "Read specs.md to create the new search function. Use heal to validate it works as described."

  7. Mix Heal SDK calls with standard Playwright actions

    Heal is designed to be used alongside standard Playwright code. By calling heal.getPage(), you get access to both the standard Playwright page object and the Heal agent object. This allows for gradual adoption, the use of existing Playwright fixtures/plugins, and the ability to drop back to raw Playwright for low-level control.
    const { page, agent } = await heal.getPage();

// Use a Heal call for a complex interaction
await agent.leftClick(
  'The contact doctor button in the first card on the left',
);

// Use a standard Playwright expectation for verification
await expect(page).toHaveURL(/doctor/);

  8. Provide feedback on Heal test verdicts

    Users can improve Heal's accuracy in sorting bugs from noise by providing feedback on any verdict. This can be done via thumbs-up/thumbs-down reactions or by using the 'Report flake' button within the Slack app.

  9. Report security vulnerabilities to Heal

    Security vulnerabilities should be reported confidentially to security@heal.dev. Heal follows responsible disclosure practices, acknowledging reports within 24 hours and providing an initial assessment within 72 hours. Encrypted communication is supported via PGP key (available upon request).

  10. Trigger Heal tests using the heal-trigger GitHub Action

    The heal-dev/heal-trigger GitHub Action allows you to integrate Heal test runs into your CI/CD workflows. To set it up, add your Heal API key as a GitHub repository secret (e.g., HEAL_API_KEY) and include the action in your workflow YAML.
    - name: Run Heal tests
  uses: heal-dev/heal-trigger@v1
  with:
    api-key: ${{ secrets.HEAL_API_KEY }}

  11. Quick start with the Heal starter repository

    Use the starter template to quickly evaluate Heal's capabilities. This path includes the necessary Playwright version and dependencies.
    # 1. Clone the starter repo
git clone https://github.com/heal-dev/heal-test-template.git
cd heal-test-template

# 2. Install dependencies
npm install

# 3. Authenticate
npx heal login

# 4. Run the autopilot
npx heal autopilot

  12. Install and authorize the Heal Slack app

    To integrate Heal with Slack, navigate to Settings → Notifications in the Heal dashboard and select Connect Slack. You must authorize the app to read channel info, send messages, and handle slash commands. Once authorized, the Heal bot joins your workspace. To start receiving notifications in a specific channel, invite the bot using the /invite @Heal command. You can connect multiple workspaces and multiple channels per workspace.
    /invite @Heal