accelint-ac-to-playwright

What this skill does

# AC To Playwright

**MANDATORY - READ ENTIRE FILE**: Before processing ANY acceptance criteria, you MUST read [`references/acceptance-criteria.md`](references/acceptance-criteria.md) (~175 lines) completely from start to finish. **NEVER set any range limits when reading this file.** It is the authoritative source for AC writing rules and mappings.

**Note on test-hooks.md**: Load `references/test-hooks.md` when converting AC → JSON plans or when running Assessment mode — it contains the controlled vocabulary for area/component/intent target naming patterns. **Do NOT load** when converting plans → tests (translation script handles this automatically).

## Intent Detection

The skill supports two modes based on user phrasing:

**Assessment mode** (triggers on):
- "review these AC"
- "evaluate these AC"
- "check if these AC are ready"
- "can these AC be converted as-is"
- "are these AC automation-ready"
- "assess these acceptance criteria"

**Full conversion mode** (triggers on):
- "convert these AC"
- "generate tests from AC"
- "turn AC into Playwright tests"
- "create test automation"

Assessment mode analyzes AC text only (no artifact generation). Full conversion mode generates plans and tests.

### Assessment Workflow
0. **Detect intent**: User asks to review/evaluate/assess/check AC readiness.
1. **Prepare for the task**:
  - Read `references/acceptance-criteria.md` and `references/test-hooks.md`.
  - Work one input file at a time.
2. **Analyze AC text** against all conversion requirements:
   - **Structure & Format**:
     - Bullet format: proper `- ` markers for each AC
     - Gherkin format: valid Feature/Scenario/Examples/Given/When/Then/tags structure
     - Step ordering: all Givens → all Whens → all Thens (no mixing within a scenario)
   - **Targets** (semantic validation):
     - Every action specifies a target
     - Target meets the area/component/intent pattern (all three parts present)
     - Area matches controlled vocabulary from `test-hooks.md` (nav, header, footer, form, drawer, card, toast, modal, table, page, area)
     - Component matches controlled vocabulary (button, link, input, dropdown, checkbox, radio, text, div, component)
     - Intent is present
   - **Actions**:
     - Verbs are recognized and mappable to Playwright actions (click, fill, select, drag)
     - No vague verbs (interact, use, hover without x/y coordinates)
     - Fill/select actions have quoted literal values (not "a valid email" or "any value")
   - **Expected Outcomes**:
     - Explicitly stated (not implied or inferred)
     - Measurable (specific text content, element, or state)
     - Visibility changes use trigger words (appears, shows, hides, visible, see)
3. **Report results**:
   - If issues found: Report "❌ AC are not conversion-ready" with detailed issue list (see output format below)
   - If no issues: Report "✓ AC are conversion-ready" with validated checklist
   - Do NOT generate any files (no JSON plans, no test files)
   - Report results for all input files - do not stop Assessment mode after a single failure to ensure all issues are surfaced to the user at once.

### Conversion Workflow
0. **Detect intent**: User asks to generate/convert/write tests from AC files.
1. **Run Assessment mode**:
  - Run Assessment mode against all input files and report pass/fail result.
  - If Assessment mode reported any failures across all files, **STOP**. **Do not** proceed with the rest of Conversion mode.
2. **Prepare for the task**:
  - Require the user to explicitly provide output directories for plans, tests, and summaries before writing any files.
  - Read `references/acceptance-criteria.md`.
  -  Work one input file at a time. Do not parallelize so that errors in one file's workflow do not affect other files' workflows.
  -  Derive suite name, test names, startUrl, steps, targets, tags, and source metadata per the rules below.
3. **JSON test plan**:
  - Build a JSON test plan that conforms to `references/plan-schema.ts`.
  - Validate the test plan and report results.
  - If validation failed, **stop**. Do not write the plan. Skip the rest of these steps for the current input file and move on to the next input file.
  - If validation passed, write the plan to the user-specified output directory: `<plans-output-dir>/<suite-slug>.json`.
4. **Translate the plan to tests**:
  - Once the plan file is written, translate the plan with `scripts/translate-plan-to-tests.ts`.
  - Write the test suite file to the user-specified output directory: `<tests-output-dir>/<suite-slug>.spec.ts`.
  -  Append a summary entry to the batch JSON file in the user-specified summary directory (one batch file per run).
5. **Next steps**: 
  - Work on the next input file, if any remain.
  - After all files are processed:
    - Copy `skills/accelint-ac-to-playwright/assets/fixtures/` directory to `<tests-output-dir>/fixtures/`. This directory contains shared test utilities (`error-handling.ts` and `console-tracking.ts`) that generated tests import from.
    - Ask the user if they would like a Playwright config template. If yes, copy `skills/accelint-ac-to-playwright/assets/templates/playwright.config.ts` into the user‑specified summaries location.

## Recognition Patterns
Before processing AC, identify these quality signals:

**Good AC** (can process directly):
| Check | Question | If NO → Action |
|-------|----------|----------------|
| **Targets** | Does every action specify area.component.intent? | Ask user to clarify which specific element |
| **Values** | Are all fill/select values quoted literals? | Ask user for exact values to use |
| **Outcomes** | Are expectations measurable (specific text/element/state)? | Ask user what exactly to verify |

**Bad patterns** (ask the user questions):
- "interact with" (and other similar language) → too vague, agent can't map to Playwright action
- Dropdown: "select the first option" → fails, needs exact text
- Always quote exact literals: `'[email protected]'` not "a valid email"

The above table directs you to ask for clarifications because guessing creates tests that fail unpredictably.

## Naming Transformations

**Input to output mapping**: One AC file → one suite → one plan file (`<plans-dir>/<suite-slug>.json`) → one test file
- `.md` bullet-style: each `- ` bullet = one test
- `.feature` Gherkin: each Scenario = one test; each Examples row in Scenario Outline = one test

**Output structure**: After conversion completes, the test output directory will contain:
- `<suite-slug>.spec.ts` files (one per AC file)
- `fixtures/` directory with shared utilities:
  - `fixtures/error-handling.ts` - failure artifact attachment helper
  - `fixtures/console-tracking.ts` - console message tracking helper

**Important for users**: When copying generated tests to your Playwright project, copy both the `.spec.ts` files AND the `fixtures/` directory. Tests import from these fixtures and will fail to compile without them.

| Input | Suite Name | Test Name | Output Slug |
|-------|------------|-----------|-------------|
| `.feature` | `Feature:` text → lowercase → capitalize first | Scenario text (lowercase, ~64 char limit) + ` (params)` for Scenario Outlines | suite name → lowercase, spaces to dashes |
| `.md` | filename → lowercase → dashes to spaces → capitalize first | Summarize bullet intent (present tense, lowercase, ~64 char) | suite name → lowercase, spaces to dashes |

**Scenario Outline parameters**: Use shortest left-to-right column combo that uniquely identifies each row, joined with `/`.

Example:
```
Examples:
  | username | password | message       |
  | user1    | pass1    | Welcome user1 |
  | user2    | pass2    | Welcome user2 |
```
Appends ` (user1/pass1)` and ` (user2/pass2)` respectively.

## Tags (Gherkin only)
- Feature-level tags -> suite tags.
- Scenario-level tags -> test tags.
- Do not include suite tags in test tags; drop duplicates at the test level.
- If no test tags remain, omit tags field for that test.
- Tag values i