HATCH

Test Reliability Infrastructure

██   ██  █████  ████████  ██████ ██   ██
██   ██ ██   ██    ██    ██      ██   ██
███████ ███████    ██    ██      ███████
██   ██ ██   ██    ██    ██      ██   ██
██   ██ ██   ██    ██     ██████ ██   ██

---

What is Hatch?

Hatch is a Test Reliability Infrastructure layer that automatically heals broken Playwright locators. It integrates directly into your CI pipeline and helps reduce flaky test maintenance.

---

Installation

npm install -g hatch

---

Quick Start

1. Run Tests with Healing

 get healing suggestions
# Run tests andhatch run --tests "tests/**/*.spec.ts"

# Dry run - show suggestions without applying
hatch run --tests "tests/**/*.spec.ts" --dry-run

# Apply fixes automatically
hatch run --tests "tests/**/*.spec.ts" --apply

2. Heal a Single Locator

hatch heal ".submit-btn" --snapshots '[{"ref":"e1","tag":"button","role":"button","label":"Submit"}]'

3. Generate Test Code

hatch generate "Navigate to login" "Enter username" "Click submit" -l typescript

---

Example: Before & After

Broken Test

test('should login', async ({ page }) => {
  await page.locator('.btn-primary').click();           // BROKEN
  await page.locator('#username').fill('admin');        // BROKEN
  await page.locator('.card input').first().fill('pass'); // BROKEN
});

After Hatch Healing

test('should login', async ({ page }) => {
  await page.getByRole('button', { name: 'Login' }).click();
  await page.getByLabel('Username').fill('admin');
  await page.getByLabel('Password').fill('pass');
});

---

CLI Output Example

$ hatch run --tests "tests/**/*.spec.ts"

  Running Playwright tests...
  Pattern: tests/**/*.spec.ts

  Found 3 test failures:

  login.spec.ts:15 - should accept username input
    Error: LocatorNotFound
    Broken: #username
    Fixed:  getByLabel('Username')
    Confidence: 90%

  login.spec.ts:20 - should accept password input
    Error: LocatorNotFound
    Broken: .card input
    Fixed:  getByLabel('Password')
    Confidence: 90%

  Summary:
    Total failures: 3
    Analyzed: 3
    Mode: PREVIEW

---

Locator Priority

Hatch uses confidence-based prioritization:

Strategy	Confidence	Resilience
getByRole	95%	Highest
getByLabel	90%	Very High
getByTestId	85%	High
getByPlaceholder	80%	High
getByText	60%	Medium
locator (CSS)	30%	Low

---

CI Integration

GitHub Actions

name: Tests with Hatch Healing

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests with Hatch
        run: npx hatch run --tests "tests/**/*.spec.ts" --dry-run --output hatch-report.json
      
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: hatch-report
          path: hatch-report.json

---

Commands

Command	Description
hatch run	Run tests and heal locators
hatch heal	Heal a single locator
hatch generate	Generate test code
hatch capture	Capture page snapshots
hatch cache	Manage cache

---

Options

Option	Description
--dry-run	Show suggestions without applying
--apply	Apply fixes automatically
--output	Save JSON report
--confirm	Confirm before applying

---

Status

Feature	Status
Locator Healing	✅ Stable
Test Generation	✅ Stable
Failure Parsing	✅ Stable
CI Integration	✅ Stable
Failure Grouping	✅ Stable

---

Examples

See examples/playwright-broken-suite/ for a complete working example with:

• 10 test cases
• 5 broken locators
• Cascading failure scenario
• GitHub Actions workflow

---

License MIT © 2026 Ricardo Costa