test-automation

Forbidden invocations

NEVER invoke /sdd-* skills from this workflow. SDD is an optional user-installed ceremony; this skill ships self-contained and does not chain SDD under any condition. If you need to refactor KATA, fixtures, cli/, scripts/, or api/schemas/ pipeline, exit this skill first and invoke /framework-development — which itself runs Plan → Code → Verify → Archive natively (no SDD required).

This boundary is mechanical, not advisory: scripts/lint-skills.ts rejects any /sdd- mention outside this section. See: .agents/skills/agentic-qa-core/references/skill-composition-strategy.md §4 (governs users who manually install SDD).

Test Automation — Plan, Code, Review

Produce KATA-compliant automated tests for an existing Playwright + TypeScript project. Three phases, always in this order: Plan → Code → Review. Never jump straight to code.

KATA (Komponent Action Test Architecture) rewires the usual Page Object pattern. If you write tests the "standard" way, most will be rejected at review. Load the relevant reference before writing code in that area.

---

Dependencies

Requires agentic-qa-core. Loads on demand:

• agentic-qa-core/references/test-design-doctrine.md — MANDATORY before planning which ATCs to write from acceptance criteria. Governs the 1:N ATC derivation, the formal-technique triggers (incl. BVA, which KATA's EP-merge rule does NOT replace), and the floor-not-ceiling coverage model.
• agentic-qa-core/references/briefing-template.md, agentic-qa-core/references/dispatch-patterns.md, agentic-qa-core/references/orchestration-doctrine.md, agentic-qa-core/references/session-management.md, agentic-qa-core/references/preflight-gate.md, agentic-qa-core/references/adr-doctrine.md — cited inline by the sections that use them.

Compact Rules

Test-design doctrine (binding — full canon: agentic-qa-core/references/test-design-doctrine.md):

• "All ACs covered" is the FLOOR, not the success bar. The ATC set must also cover risk-beyond-AC: invalid/boundary inputs, auth/error paths, state transitions, and anomalies the AC is silent on.
• 1:N is the default: one AC maps to multiple ATCs. EP-merge collapses same-behavior inputs INSIDE one partition into a parameterized ATC — it must NEVER collapse across distinct partitions, boundaries, or states. BVA cases are required wherever a range/limit/length/date-window exists (EP alone misses off-by-one).
• Apply techniques by trigger: EP always; BVA on ranges/limits; State-Transition for stateful flows; Decision Table when 2+ conditions interact; Pairwise when 3+ combinable factors (log the reduction).
• Parametrize for artifact economy: same-behavior data variants → ONE parameterized @atc (fixture / data-factory rows iterated by the test) per partition, NOT N ATCs; split only when action / outcome / state differs. (Canon: doctrine §"Part 2.5".)
• An AC is the business assertion; an ATC is its concrete exploration (Precondition + Action + Assertions). Run the Test-Design Checklist before finalizing the plan.

Test-automation operational rules:

• Plan → Code → Review, always in order. Only automate Candidate verdicts from /test-documentation.
• Fixture selection: API-only → { api } (no browser); UI-only → { ui }; hybrid → { test }.
• ATC = atomic mini-flow; NEVER calls another ATC. Reusable chains → a Steps module.
• Max 2 positional params (3+ → object param). Locators inline (extract only at 2+ uses). Imports via aliases (@api/, @schemas/, @utils/) — no relative imports.
• Public methods fail fast; utilities silent-fail (return null). Validate against kata-manifest.json before adding components/ATCs (anti-duplication gate).

Read full SKILL.md when: writing KATA component code, choosing fixtures for a hybrid flow, or applying the Phase 3 review checklist.

---

Mode routing

Resolve mode before any readiness preflight or session workflow.

• explain: selected by the legacy break-down-tests alias or an explicit request to explain existing automated tests. Forward $ARGUMENTS unchanged, load only references/explain-tests.md, produce its read-only report, then stop. Do not create session state, run Plan -> Code -> Review, edit tests, regenerate kata-manifest.json, or call Jira/TMS.
• automate (default): all normal KATA planning, coding, and review triggers. Continue with the workflow below.

If the invocation could mean either explanation or implementation, ask which outcome is wanted. Never infer implementation from a read-only explanation request.

---

Subagent Dispatch Strategy

Orchestration & Session contracts: this skill follows agentic-qa-core/references/orchestration-doctrine.md (mandatory subagent dispatch — main thread is command center) AND agentic-qa-core/references/session-management.md (Phase 0 resume check, plan-first persistence at .session/<skill-slug>/<scope>/, archive on completion). Phase 0 (resume check) and Phase 1 (plan write) are NOT optional. The orchestrator also applies the per-stage Definition-of-Done gates in agentic-qa-core/references/stage-gates.md: verify a stage's DoD (planning stages include the Test-Design Checklist) BEFORE recording its progress checkpoint and advancing.

This skill is per-scope: <scope> = <JIRA-KEY> (ticket-driven / regression-driven) or <module-slug> (module-driven). Session state lives at .session/test-automation/<scope>/{plan.md, progress.md} per agentic-qa-core/references/session-management.md §3 + §9. The session plan.md is a thin INDEX that cites the canonical domain artifacts (spec.md, automation-plan.md, atc/*.md) under the Epic's test-specs/ tree (.context/PBI/epics/EPIC-<KEY>-<slug>/test-specs/<scope>/) — domain content stays in the existing PBI tree, not duplicated.

This skill is compliant with the doctrine in AGENTS.md §"Orchestration Mode (Subagent Strategy)" and the session contract in .agents/skills/agentic-qa-core/references/session-management.md. Every dispatch follows the 7-component briefing format defined in .agents/skills/agentic-qa-core/references/briefing-template.md, and the pattern selected per phase matches the decision guide in .agents/skills/agentic-qa-core/references/dispatch-patterns.md. The Plan, Code, and Review phases each carry distinct context-isolation needs — Plan keeps KATA architectural reads out of the orchestrator, Code isolates multi-file edits, Review fans out three independent verifiers in parallel.

Stage	Pattern	Subagent role
Plan (spec.md + automation-plan.md)	Single	one Plan subagent returns the two artifacts; protects orchestrator from KATA architectural reads
Code (writing E2E or API tests)	Sequential	one Code subagent per scope (module = 1 subagent per TC; ticket = 1 subagent total); edits-many-files inside isolates context
Review — bun run test	Parallel (sub-stage)	one Verifier subagent runs the test suite
Review — bun run types:check	Parallel (sub-stage)	one Verifier subagent runs typecheck
Review — bun run lint:check	Parallel (sub-stage)	one Verifier subagent runs lint
Review aggregation + merge/reject decision	Single	inline — orchestrator reads the 3 Verifier reports and decides

• Code phase scope rule: each Code subagent edits multiple files in isolation, returns a list of changed files + a one-line summary per file. The orchestrator never reads the diffs — only the summary. If the user wants to see actual diffs, the orchestrator runs git diff inline after the subagent returns.
• On any Verifier failure: STOP, return the failing report verbatim to the user, do NOT auto-fix the test code, do NOT re-dispatch the Code phase without user approval. See .agents/skills/agentic-qa-core/references/orchestration-doctrine.md.
• MANDATORY context doc for Plan + Code briefings: include kata-manifest.json (root) in the "Context docs" component (item 2 of the 7-component briefing). Without it the subagent will scan tests/components/** directly, burn tokens, and risk proposing duplicates. See Critical Rule #12 in AGENTS.md.

---

Inputs — read these first, in this order

Canonical reading order for any AI starting cold on a test-automation workflow. Read in order; stop earlier when later inputs add no signal for the scope at hand.

1. kata-manifest.json (root) — authoritative registry of every Component (api[], ui[]) and every @atc('TICKET-ID') ID. Anti-duplication gate per Critical Rule #12 in AGENTS.md. MUST load before proposing any new Page, Api, Steps module, or @atc ID.

2. .agents/skills/test-automation/references/kata-architecture.md + .agents/skills/test-automation/references/typescript-patterns.md — full doctrine for KATA layers (TestContext / Base / Domain / Fixture), ATC identity, fixture selection, import-alias rules, params contracts.

3. tests/components/ — existing Api / Page / Steps shape on disk. Establishes naming, helper-vs-ATC split, fixture registration patterns to follow.

4. The Story's implementation-plan.md (dev plan) + the ATP under .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ — Jira-synced, READ-ONLY caches. Jira is source of truth; NEVER hand-write these. Materialize via bun run jira:sync-issues get <STORY-KEY> --include-comments, then read the ENTIRE synced Story folder — every per-field .md (story.md, acceptance-criteria.md, scope, business rules, etc.) plus comments.md — not just one field. Omitting ACs, scope, business rules, or comment context produces incomplete ATCs. The ATP read is modality-aware (resolve via .agents/project.yaml testing.tms_cli, same gate as /test-documentation §Phase 0):

   • Modality jira-native: ATP = Story field {{jira.acceptance_test_plan}} → synced acceptance-test-plan.md in the Story folder (from the same jira:sync-issues get <STORY-KEY> --include-comments).
   • Modality jira-xray: ATP = Test Plan issue description → bun run jira:sync-issues get <ATP_KEY> → test-plans/ATP-<KEY>-<slug>.md; per-TC run results come from [TMS_TOOL] (xray-cli), not the sync. Filename note: the acronym prefix comes from a conforming ladder title; a Plan or Execution whose title does not follow the grammar keeps the legacy TESTPLAN- / TESTEXEC- / RETESTEXEC- prefix.

   The dev implementation-plan.md carries the implementation approach + (when produced by /test-documentation) the per-TC candidate verdict and component mapping. Cite from the session plan.md rather than duplicating. NOTE: this is the Story-folder dev implementation-plan.md — do NOT confuse it with the hand-authored automation plan (test-specs/<scope>/automation-plan.md) you write in Phase 1.

5. The Story's AC (acceptance criteria) — source of truth for scenarios that become ATCs. Read from the same synced .md files (acceptance-criteria.md / story.md) produced by bun run jira:sync-issues get <STORY-KEY> --include-comments. NEVER use [ISSUE_TRACKER_TOOL] view for these custom fields — view returns null for customfield_*. If a field is absent from the instance, the sync emits a pointer stub and the content lives in comments/description per .agents/jira-required.yaml fallback:. Resolve the issue key from the scope picker. TC note: a TC body = the Test issue description (synced both modalities via bun run jira:sync-issues get <TEST-KEY>); the Xray Gherkin / Test-Steps plugin field is NOT synced — it mirrors the description, so read the synced TC .md for Gherkin/steps.

6. api/schemas/ — OpenAPI-derived TypeScript types. Refresh via bun run api:sync if stale. Required for any Api component touching a new endpoint.

7. .env — credentials (LOCAL_USER_EMAIL, STAGING_USER_PASSWORD, etc.) read via config.testUser from @variables. Never hardcode; never guess.

---

Readiness Preflight Gate (MANDATORY — runs before Phase 0)

Full doctrine: agentic-qa-core/references/preflight-gate.md. Runs FIRST, before the resume check and scope picker. Two laws: (1) args-as-answers — the scope, ticket key, and "API test" vs "E2E test" are provided args; ask only the gaps. (2) probe, don't assume. Surface gaps + REDs as ONE AskUserQuestion checklist; self-fix with approval + explanation; STOP on any blocking RED. Note: this is distinct from the anti-duplication "Pre-flight checklist" inside Phase 1 (which cross-checks kata-manifest.json for reuse) — this gate is about tools + env being ready to write and run code. Generic baseline (env resolution, test-user creds, secret/restart handling, the two laws, output contract) is inherited from the reference §3.1 — not repeated here. Below is only this skill's specific capability delta.

Capability	Need	Why here
Framework adapted (artifacts present)	REQUIRED	Cannot write project ATCs against the generic Example* scaffolds the boilerplate ships. Probe the reference §4 ADAPTED signals; still generic → STOP and tell the user to run /project-discovery → /adapt-framework themselves. The gate NEVER auto-runs them.
Dev toolchain	REQUIRED	The Review gate runs bun run test / bun run types:check / bun run lint:check. Resolve them at t=0, not at Phase 3. bun install if a dep is missing.
kata-manifest.json clean	REQUIRED	Anti-duplication source of truth (Critical Rule #12). bun run kata:manifest:check clean before proposing components/ATCs; bun run kata:manifest if stale.
Active env + test-user creds	REQUIRED	Authored tests run live against <<ACTIVE_ENV>>. Env reachable + .env creds for the env (per role if multi-role).
Playwright browsers	REQUIRED	bunx playwright resolves + chromium installed (bun run pw:install).
OpenAPI MCP (schema read-only) + api/schemas/ synced	SCOPE — API/integration tests; needed at Phase 1 Plan too	Phase 1 explores endpoints (via the openapi MCP, schema-read-only) to design ATCs + classify test-data — plan-time, not just run-time. Api components consume OpenAPI-derived types (api/schemas/; refresh bun run api:sync); authenticated test-code calls use the Playwright API fixture (.auth/api-state.json from bun run api:login) — no API_TOKEN/MCP injection, no restart.
DBHub MCP	SCOPE — data setup/validation; needed at Phase 1 Plan too	Phase 1 explores the schema (via the dbhub MCP) to design data fixtures (Discover / Modify / Generate) — plan-time, not just run-time. dbhub answers a schema probe; DBHUB_* in .env. Unset → fill .env + RESTART.
Issue-tracker ([ISSUE_TRACKER_TOOL])	SCOPE — ticket/regression-driven	ATP + AC reads via bun run jira:sync-issues; TMS modality for the ATP source. Pure module-driven from an existing spec may not need it.

Surfaces (UI vs API vs both) follow the chosen planning scope + the ATCs Phase 1 designs — NEVER a user question (reference §5). After the gate clears (generic baseline + the surface tools the scope needs GREEN), continue to Phase 0 below.

---

Phase 0 — Resume check (MANDATORY, inline)

Before picking the planning scope, run the session resume contract from agentic-qa-core/references/session-management.md §4:

1. Determine the prospective <scope> from the invocation context (ticket key, regression-driven TC, or module slug — see "Pick the planning scope first" below).
2. Check .session/test-automation/<scope>/progress.md.
3. If it does NOT exist → proceed to scope picker + Phase 1.
4. If it DOES exist:
   • Read plan.md (thin index) + the tail of progress.md.
   • Read the cited canonical spec.md / automation-plan.md / atc/*.md under .context/PBI/epics/EPIC-<KEY>-<slug>/test-specs/<scope>/ for the domain content.
   • Surface to the user: last completed phase (Plan / Code / Review) + next phase + open Review findings if any.
   • Offer resume / restart / abort. On restart, archive to .session/.archive/<YYYY-MM-DD>-test-automation-<scope>-aborted/ before proceeding.

Phase 0 is inline (no subagent). It runs in <1 minute on a cold cache.

---

Pick the planning scope first

Every automation session starts by choosing one of three planning scopes. Pick once, then follow the Plan → Code → Review pipeline.

Scope	Input	Output	Use when
Module-driven (Macro)	A module name + list of candidate TCs	One module spec + N ATC specs	Batch-automating an entire module (10+ tests). First pass on a new area.
Ticket-driven (Medium)	A single ticket/story ID with scenarios	One implementation plan for that ticket	Automating one user story end-to-end. Default for sprint work.
Regression-driven (Micro)	One specific TC (often after a bug fix)	One ATC implementation plan	Adding a single regression test after a fix. Smallest unit of work.

When in doubt, ask the user which scope. Never assume "module" just because multiple TC IDs appear in the briefing.

These scopes consume the Candidate verdicts from /test-documentation (Stage 4) — only Candidate TCs reach automation; Manual / Deferred are terminal. The mapping from that skill's 4 documentation scopes: Module (Macro) ← module-driven, Ticket (Medium) ← ticket-driven, Regression-driven (Micro) ← bug-driven. Candidates from an ad-hoc / exploratory documentation session enter under whichever fits — a module batch, or regression-driven for a single TC.

---

Workflow — Plan → Code → Review

Phase 1: Plan         -> Phase 2: Code             -> Phase 3: Review
(spec / plan)            (component + test file)      (KATA compliance)
        |                         |                             |
  .context/PBI/epics/        tests/components/**         Review checklist
    EPIC-<KEY>-<slug>/       tests/e2e/** or                (pass/fail)
    test-specs/<scope>/      tests/integration/**
    spec.md
    automation-plan.md
    atc/*.md                 Register in fixture

Each phase has a gate. Do not start Code before the Plan is written and approved. Do not close out a ticket until Review passes.

Phase 1 — Plan

MUST-load before any planning: kata-manifest.json (root). It lists every Component and every ATC currently in the codebase. Use it to identify reuse, avoid duplicate Page/Api classes, and avoid minting an @atc('PROJ-XXX') ID that is already taken. This is enforced by Critical Rule #12 in AGENTS.md and by the husky pre-commit gate.

Pre-flight checklist (anti-duplication — run before writing the plan):

• Load kata-manifest.json. Cross-check every proposed TC ID against components.api[].atcs[].id and components.ui[].atcs[].id. If a match exists, the TC is already automated — re-scope or reuse.
• Cross-check every proposed Component name against components.api[].name and components.ui[].name. If a match exists, extend the existing class — do not create a new one.
• If reuse opportunity exists (same flow already covered by a Steps method or ATC), adapt the plan to extend rather than rebuild.

Write the canonical domain plan file(s) for the chosen scope under the Epic's test-specs/ tree, .context/PBI/epics/EPIC-<KEY>-<slug>/test-specs/<scope>/ (spec.md, automation-plan.md, atc/*.md). These are NON-Jira hand-authored files (committed to git). The automation automation-plan.md is distinct from the Story-folder dev implementation-plan.md (Jira-synced, read-only). The plan answers:

• Which scenarios from the ticket become tests, which become ATCs, which are shared preconditions (Steps)?
• Which components already exist (tests/components/api/*Api.ts, tests/components/ui/*Page.ts) and which need to be created?
• What test data is required? Classify by Discover / Modify / Generate (never assume data exists in staging).
• Which fixture will the test use -- {api}, {ui}, or {test}? Do any shared preconditions call for a Steps class (tests/components/steps/*Steps.ts), instantiated directly in the test?
• Which ATC IDs (from the TMS) map to which component methods?

Also write the session index plan.md at .session/test-automation/<scope>/plan.md per agentic-qa-core/references/session-management.md §6. This is a THIN INDEX — Goal, Inputs (cites the canonical artifacts above), Approach, Phase breakdown table, Risks, Verification checklist, Cross-references. It does NOT duplicate the domain content; it points to it.

Use the dispatch defined in §Subagent Dispatch Strategy: Single. Full briefing in references/planning-playbook.md §Plan dispatch.

Present the plan to the user. Wait for approval before coding. After approval, the orchestrator appends ## Phase 1 — Plan — <ts> with status: completed, artifacts_touched: [list of domain + session files], next: Phase 2 — Code to .session/test-automation/<scope>/progress.md.

Phase 2 — Code

Use the dispatch defined in §Subagent Dispatch Strategy: Sequential (one subagent per scope unit). The subagent loads references/e2e-patterns.md and references/api-patterns.md per scope.

Skills to load in every Code subagent (mandatory): /playwright-best-practices (community, project-installed) for upstream Playwright/TypeScript patterns — flaky-test fixes, POM vs fixtures, axe-core, auth/OAuth, fixtures lifecycle, perf budgets, i18n, component testing. Load alongside /test-automation (this skill, project-authored) — the two are complementary: KATA-specific rules (ATC identity, inline locators, fixture selection) come from here; generic Playwright craft comes from /playwright-best-practices. Add /playwright-cli only when the subagent also needs to drive a real browser session (snapshot/trace/record) during code-time exploration.

Implement in this order:

1. Types at top of component file (payloads, responses, domain DTOs).
2. Component class extending ApiBase or UiBase. Helpers first (no decorator), ATCs second (@atc('TICKET-ID')).
3. Register the component in tests/components/ApiFixture.ts or UiFixture.ts as appropriate. Steps classes (tests/components/steps/*Steps.ts) are NOT registered in any fixture — tests and setup files instantiate them directly (see ExampleSteps.ts).
4. Test file under tests/e2e/{module}/ or tests/integration/{module}/, using the correct fixture.
5. Run + verify, in this exact order -- do not skip steps:

bun run test <path/to/new.test.ts>   # does it pass?
bun run types:check                   # tsc --noEmit, no errors
bun run lint:check                         # ESLint, no errors

If any step fails, fix before moving to Review.