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: .claude/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 (Component 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, ./dispatch-patterns.md, ./orchestration-doctrine.md, ./session-management.md, ./preflight-gate.md, ./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.

---

Subagent Dispatch Strategy

> Orchestration & Session contracts: this skill follows ./orchestration-doctrine.md (mandatory subagent dispatch — main thread is command center) AND ./session-management.md (Phase 0 resume check, plan-first persistence at .session///, 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 ./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: ` = (ticket-driven / regression-driven) or (module-driven). Session state lives at .session/test-automation//{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--/test-specs//`) — domain content stays in the existing PBI tree, not duplicated.

This skill is compliant with the doctrine in CLAUDE.md §"Orchestration Mode (Subagent Strategy)" and the session contract in .claude/skills/agentic-qa-core/references/session-management.md. Every dispatch follows the 6-component briefing format defined in .claude/skills/agentic-qa-core/references/briefing-template.md, and the pattern selected per phase matches the decision guide in .claude/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 .claude/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 6-component briefing). Without it the subagent will scan tests/components/** directly, burn tokens, and risk proposing duplicates. See Critical Rule #12 in CLAUDE.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 CLAUDE.md. MUST load before proposing any new Page, Api, Steps module, or @atc ID.
2. .claude/skills/test-automation/references/kata-architecture.md + .claude/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--/stories/STORY--/ — Jira-synced, READ-ONLY caches. Jira is source of truth; NEVER hand-write these. Materialize via bun run jira:sync-issues get --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 --include-comments).
• Modality jira-xray: ATP = Test Plan issue description → bun run jira:sync-issues get → test-plans/TESTPLAN--.md; per-TC run results come from [TMS_TOOL] (xray-cli), not the sync.

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//automation-plan.md) you write in Phase 1.

1. 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 --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 ); the Xray Gherkin / Test-Steps plugin field is NOT synced — it mirrors the description, so read the synced TC .md for Gherkin/steps.
2. api/schemas/ — OpenAPI-derived TypeScript types. Refresh via bun run api:sync if stale. Required for any Api component touching a new endpoint.
3. .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 >. 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 + API_TOKEN + api/schemas/ synced | SCOPE — API/integration tests; needed at Phase 1 Plan too | Phase 1 explores endpoints (via the openapi MCP) to design ATCs + classify test-data — so the MCP is plan-time, not just run-time. Api components consume OpenAPI-derived types (api/schemas/; refresh bun run api:sync); authenticated calls need a live API_TOKEN (api-login flow, reference §6 → 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 `` from the invocation context (ticket key, regression-driven TC, or module slug — see "Pick the planning scope first" below).
2. Check .session/test-automation//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--/test-specs// 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/-test-automation--aborted/ before proceeding.

Phase 0 is inline (no subagent). It runs in Phase 2: Code -> Phase 3: Review (spec / plan) (component + test file) (KATA compliance) | | | .context/PBI/epics/ tests/components/ Review checklist EPIC--/ tests/e2e/ or (pass/fail) test-specs// tests/integration/** spec.md automation-plan.md atc/*.md

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: upex-galaxy
• Source: upex-galaxy/agentic-qa-boilerplate
• License: MIT

Install and usage instructions live in the source repository linked above.