---
name: ai-qa-workflow
description: AI QA Workflow skill — Playwright E2E testing with Allure, Applitools, self-healing, and QA Dashboard integration
agents: [qa-planner, qa-generator, qa-healer]
---

# AI QA Workflow Skill

You are an expert QA automation engineer working on the **AI QA Workflow Template** project.

This project has a complete pipeline: user story → test plan → test generation → execution → self-healing → reporting + dashboard.

## 1. Project Architecture

### Directory Structure
```
user-story/          # User stories (input)
specs/               # Test plans (generated by planner)
tests/               # Playwright .spec.ts files (generated by generator)
test-results/        # Run outputs (execution-output.json, execution-result.json, healing-report.json)
allure-results/      # Allure raw results (generated by allure-playwright reporter)
qa-dashboard/        # Express dashboard for visualizing results
scripts/             # Workflow engine (executor.js, reporter.js, healer.js, etc.)
.opencode/agents/    # Subagent definitions (qa-planner, qa-generator, qa-healer)
.qa-context/         # Pipeline state, selectors, traceability, heal history
```

### Pipeline Phases
1. **Plan** → `specs/<story>.md`
2. **Generate** → `tests/<story>.spec.ts`
3. **Execute** → `test-results/run-<timestamp>/`
4. **Heal** → auto-fix failing tests
5. **Report** → markdown report + Allure + Dashboard

## 2. Playwright Configuration

### Required Reporters in `playwright.config.ts`
```typescript
reporter: [
  ['list'],
  ['json', { outputFile: 'test-results/playwright-report.json' }],
  ['html', { outputFolder: 'playwright-report' }],
  ['allure-playwright'],
]
```

The **json** reporter feeds `executor.js` parsing. The **allure-playwright** reporter writes to `allure-results/`. Both are critical.

### Output Paths
- Playwright HTML report: `playwright-report/index.html`
- JSON results: `test-results/playwright-report.json`
- Allure results: `allure-results/`
- Screenshots (on failure): `test-results/screenshots/` or `test-results/run-<id>/`

### Running Tests
| Command | What it does |
|---------|-------------|
| `npx playwright test` | Direct run — saves results to JSON, HTML, Allure (via config) |
| `npm run qa:execute` | Workflow run — saves to `test-results/run-<id>/` with full pipeline tracking |
| `npm run qa:execute -- <test-name>` | Run a specific test via the workflow |

## 3. Executor Compatibility

The `scripts/executor.js` parses Playwright's stdout to extract test results.

### What the Executor Expects
- **Passed tests** → lines matching `  √  <test-name>` (checkmark)
- **Failed tests** → lines matching `  ×  <test-name>` (cross mark)

### Best Practices for Executor-Friendly Tests
- Use descriptive test names (no special chars that break regex)
- Keep test names concise
- Avoid ANSI codes in test names
- Each `test()` block = 1 scenario in the report

## 4. Allure Integration

### Reporter Setup
```typescript
reporter: [
  ['allure-playwright'],
]
```

### Commands
```bash
# Generate HTML report from raw results
npx allure generate allure-results --clean -o allure-report

# Open report in browser
npx allure open allure-report

# Generate and serve on-the-fly
npx allure serve allure-results
```

Allure results are auto-generated by `executor.js` after each workflow run if `allure-commandline` is installed.

The QA Dashboard serves Allure reports at `/allure-report?project=<id>`.

### Allure Labels (optional enrichment)
```typescript
import { allure } from 'allure-playwright';

test('login with valid credentials', async ({ page }) => {
  await allure.feature('Authentication');
  await allure.story('User Login');
  await allure.severity('critical');
  // ... test body
});
```

## 5. Applitools Eyes — Visual Testing

This project integrates `@applitools/eyes-playwright` for visual regression testing.

### Setup
```typescript
import { BatchInfo, Configuration, EyesRunner, VisualGridRunner } from '@applitools/eyes-playwright';
```

### Key Practices
- Use `eyes.open()` with a unique test name
- Use `eyes.check()` with `Target.window()` or `Target.region()`
- Use `eyes.close()` to submit results
- Configure `APPLITOOLS_API_KEY` in `.env`

### Applitools MCP Tools Available
- `eyes_setup_project` — initial setup instructions
- `eyes_verify_api_key` — validate the API key
- `eyes_fetch_visual_results` — fetch results after a run
- `eyes_add_checkpoints_to_test` — add visual checkpoints to existing tests
- `eyes_analyze_batch` — analyze visual diffs from a batch URL

## 6. Self-Healing Patterns

Tests must be written to maximize auto-healing success.

### DO
- Use **stable selectors**: `data-testid` > `aria-label` > `role` > `text`
- Store frequently-used selectors in `.qa-context/selectors.json`
- Wrap flaky interactions in retry logic (Playwright auto-retries by default)
- Keep tests **independent** (no shared state)
- Use `test.beforeEach` for setup, `test.afterEach` for cleanup

### AVOID
- Hardcoded CSS selectors (e.g., `div.container > ul > li:nth-child(3)`)
- `page.waitForTimeout()` — use auto-waiting instead
- Fragile text matching (use regex or `toContainText` over `toHaveText`)
- Tests that depend on execution order (breaks in parallel mode)

### Healer Protocol
1. The healer reads `.qa-context/heal-history.json` to avoid known failures
2. It uses Playwright MCP to debug and find new selectors
3. If healing fails after 2 attempts, the test gets `test.fixme()` and is classified as a defect
4. Updated selectors are saved to `.qa-context/selectors.json`

## 7. QA Dashboard

The dashboard is an Express + EJS app at `qa-dashboard/`.

### Starting the Dashboard
```bash
npm run dashboard           # Start on port 4000
npm run dashboard:dev       # Dev mode with auto-reload
```

### Dashboard Pages
| Route | Content |
|-------|---------|
| `/` | Project overview |
| `/runs` | All test runs with pass/fail/heal stats |
| `/runs/:runId` | Single run details (output, result, healing report) |
| `/analytics` | Aggregated analytics (pass rate, heal rate, duration) |
| `/allure-report` | Allure HTML report viewer |
| `/stories` | Story traceability |

The dashboard auto-shuts down 10s after the browser tab closes.

## 8. Agent Routing

This project has 3 specialized subagents in `.opencode/agents/`:

| Agent | When to use | File |
|-------|-------------|------|
| **qa-planner** | Reading user story, exploring website, writing test plan | `.opencode/agents/qa-planner.md` |
| **qa-generator** | Converting test plan into Playwright `.spec.ts` files | `.opencode/agents/qa-generator.md` |
| **qa-healer** | Debugging and fixing failing tests | `.opencode/agents/qa-healer.md` |

Route user requests to the appropriate agent based on the current pipeline phase.

## 9. Test Template (Project-Style)

```typescript
import { test, expect } from '@playwright/test';

test.describe('Feature: <name>', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/<path>');
  });

  test('<description>', async ({ page }) => {
    await page.getByRole('button', { name: '<label>' }).click();
    await expect(page.getByText('<expected>')).toBeVisible();
  });
});
```

Tests go directly in `tests/` (flat structure, not nested) and follow the naming convention `<story-name>.spec.ts`.

## 10. Quick Reference

```bash
# Workflow commands
npm run qa:plan              # Phase 1: Plan
npm run qa:generate          # Phase 2: Generate
npm run qa:execute           # Phase 3: Execute
npm run qa:heal              # Phase 4: Heal
npm run qa:report            # Phase 5: Report

# Allure
npm run qa:report:allure     # Generate Allure HTML report
npx allure serve allure-results  # Serve Allure report

# Dashboard
npm run dashboard            # Open QA Dashboard at http://localhost:4000

# Playwright
npx playwright test          # Run all tests (direct)
npx playwright test --ui     # UI mode
npx playwright show-report   # View Playwright HTML report
```
