Running tests with Heal

Heal wraps your existing Playwright tests and adds a self-healing, AI-assisted test runner on top. You run tests with:

heal test [globs...]

This command discovers Playwright tests in your project and executes them with Heal’s runtime.

Basic usage

• Run all tests:

heal test

• Run a single test file:

heal test "tests/login.spec.ts"

• Run a subset of tests using a glob:

heal test "tests/**/*.spec.ts"

Parallelism and performance

Use --concurrency to run tests in parallel:

heal test "tests/**/*.spec.ts" --concurrency 4

Guidelines:

• Tests tend to be CPU bound, so use a concurrency number that's slightly lower than your number of (v)CPUs.
• Combine with --timeout to keep individual tests from hanging.

Headless vs headed

By default Heal will follow your test's default, but you can override headless mode:

heal test --headless true    # Good for CI
heal test --headless false   # Good for local debugging

Retries and flakiness

Heal can retry failing tests to reduce flakes due to website instability and auto-fix tests.

heal test --retries 2

In end-to-end testing, the recommendation is to use 0 retries when running tests locally, and up to 2 retries when running tests against a distant web app.

We recommend using 2 retries with Heal except when debugging, because retries are also used to dynamically fix broken locators in Heal steps.

Smart waiting and AI timing

Heal introduces a few timing options to balance speed and robustness:

• --wait-before-ai <ms> – wait before grounding elements using AI
• --wait-before-cache <ms> – wait before interacting with cached elements
• --smart-wait-timeout <ms> – intelligently wait for relevant network requests to settle and DOM to be loaded before using AI

Example:

heal test --smart-wait-timeout 7000 --wait-before-ai 0

Entry point and environment

Override the entry URL for tests:

heal test --entry-point "https://staging.example.com"