---
name: e2e-heal
description: Diagnose failing Playwright tests, apply fixes, and verify by rerunning focused scope
---

# /e2e-heal - Diagnose and Repair Failing Tests

Analyze failing Playwright tests, fix the root cause, and verify by rerunning the target scope.

## Workspace

This skill supports two layouts:

- **Single-app** (`<root>/e2e/playwright.config.ts`): resolve `<workspace>/` to `e2e/`.
- **Multi-app** (`<root>/<app>/playwright.config.ts` per app, e.g. `web/`, `backoffice/`): resolve `<workspace>/` to that app's folder.

Detect from the failing test path or from the `scope` input. If ambiguous, ASK before proceeding.

## Scope

- Works inside the resolved E2E workspace.
- Accepts a module folder, a specific file, or a narrower scope.

## Knowledge References

### Required

1. `knowledge/reliability/debugging.md`
2. `knowledge/reliability/flaky-tests.md`
3. `knowledge/reliability/common-pitfalls.md`
4. `knowledge/patterns/page-objects.md`
5. `knowledge/writing-tests/locators.md`
6. `knowledge/writing-tests/assertions.md`
7. `knowledge/writing-tests/fixtures.md`
8. `knowledge/humand/conventions.md`
9. `knowledge/humand/configuration.md`

### Conditional

1. `knowledge/patterns/react-patterns.md`
2. `knowledge/patterns/data-management.md`
3. `knowledge/patterns/api-interception.md`
4. `knowledge/patterns/authentication.md`

Resolve which conditional docs apply before editing code, and list them in your working response.

Also follow:

- `rules/playwright-healer.mdc`

## Inputs

- `scope` (optional)
- `mode` (optional, for example `headed`)

## Workflow

### 0) Resolve app context

Read `.e2e/context.local.json`. If missing, suggest running `/e2e-setup` first. The healer is the most context-hungry of the E2E skills — without app source access it can only fix surface symptoms, not root causes. If the dev opts to proceed without context, declare this is **degraded mode** and skip diagnosis steps that require source reads.

When the failing test's workspace matches an `apps[<name>]` key (e.g. failing `web/tests/...` ↔ `apps.web`), use that app's `repoPath` together with `routesPath` and `pagesPath` to read routes and components during diagnosis. Services in Humand apps are mid-migration: some modules own their `services.ts` inside the module folder, others still live under a shared `src/services/`. Locate them by **searching the failing module first** (`<pagesPath>/<module>/services.ts`) and falling back to `<sourceRoot>/services/` only if nothing relevant is found there — do not rely on a top-level `servicesPath` from the context file.

### 1) Resolve the workspace and reproduce through the local contract

Resolve `<workspace>/` from the failing scope. Then read:

- the local `package.json` (workspace root in single-app, repo root in multi-app)
- `<workspace>/playwright.config.ts`
- `<workspace>/tests/auth.setup.ts`
- `<workspace>/fixtures/base.fixture.ts`

Then reproduce the failure with the narrowest useful Playwright scope (e.g. `npx playwright test --config=<workspace>/playwright.config.ts <test-path>`).

### 2) Classify the failure

Classify before fixing:

- locator drift
- route or behavior change
- timing or stabilization issue
- data isolation or permission mismatch
- locale or auth contract mismatch
- fixture or POM boundary issue
- untranslated i18n key
- unsupported complex interactive region
- real product bug

### 3) Fix at the right layer

- Prefer page object fixes first.
- Update tests only when the scenario expectation changed.
- Do not hide failures with retries or broad `try/catch`.
- If the region is not reliably automatable yet, use `test.fixme()` with an explicit reason.

### 4) Verify and capture learning

- Rerun the focused failing scope first, then the broader module scope if it turns green.
- Record the root cause and durable fix.

## Stability heuristics from recent heals

Apply these when classifying or fixing flaky UI behavior:

- Cross-entity flows can keep stale state between tabs. After creating/updating entities in one tab, force a state reset (for example revisit the route) before selecting them in another tab.
- Before destructive actions, assert the current tab/context matches the target entity table.
- For autocomplete/combobox fields, prefer deterministic interaction:
  - focus the real textbox input inside the active drawer/dialog,
  - type the target value,
  - select via `role=option` with exact name matching first.
- Row action menus may animate/re-render and detach nodes. Use stable menuitem resolution and visibility checks before clicking.
- Keep healing local (POM interaction layer) and avoid broad retries that can mask regressions.

## Out of scope

- planning new scenarios
- bulk generation from spec
