| name | test-automation |
| description | Plan, write, and review automated tests following KATA (Component Action Test Architecture) on Playwright + TypeScript. Use when writing E2E or API/integration tests, creating Page or Api components, designing ATCs, parameterizing test data, registering fixtures, or reviewing test code for KATA compliance. Triggers on: write test, automate test, create E2E test, create API test, integration test, KATA, page object, API component, implementation plan, ATC, automated test case, review test code, automate module, automate ticket, add regression test. Always load before writing any test code -- KATA fixture selection, inline-locator rule, ATC-identity rule, and import-alias requirements differ from standard Playwright conventions. Do NOT use for running suites (regression-testing), documenting TCs in Jira/Xray (test-documentation), onboarding a repo (project-discovery), or orchestrating sprint-wide testing (sprint-testing). |
| license | MIT |
| compatibility | ["claude-code","copilot","cursor","codex","opencode"] |
| complementary_categories | ["testing-e2e","testing-api","testing-component","automation-cli","accessibility"] |
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/<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 ./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 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.
-
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.
-
.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.
-
tests/components/ — existing Api / Page / Steps shape on disk. Establishes naming, helper-vs-ATC split, fixture registration patterns to follow.
-
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/TESTPLAN-<KEY>-<slug>.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/<scope>/automation-plan.md) you write in Phase 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 <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.
-
api/schemas/ — OpenAPI-derived TypeScript types. Refresh via bun run api:sync if stale. Required for any Api component touching a new endpoint.
-
.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:
- Determine the prospective
<scope> from the invocation context (ticket key, regression-driven TC, or module slug — see "Pick the planning scope first" below).
- Check
.session/test-automation/<scope>/progress.md.
- If it does NOT exist → proceed to scope picker + Phase 1.
- 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 CLAUDE.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}, {test}, or {steps}?
- 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:
- Types at top of component file (payloads, responses, domain DTOs).
- Component class extending
ApiBase or UiBase. Helpers first (no decorator), ATCs second (@atc('TICKET-ID')).
- Register the component in
tests/components/ApiFixture.ts, UiFixture.ts, or StepsFixture.ts as appropriate.
- Test file under
tests/e2e/{module}/ or tests/integration/{module}/, using the correct fixture.
- Run + verify, in this exact order -- do not skip steps:
bun run test <path/to/new.test.ts>
bun run types:check
bun run lint:check
If any step fails, fix before moving to Review.
Progress checkpoint: after each Code subagent returns (per scope unit — one per TC for module-driven, one total for ticket-driven), the orchestrator appends a phase entry to .session/test-automation/<scope>/progress.md per agentic-qa-core/references/session-management.md §7. For module-driven scope, mid-batch resume reads the entries and skips already-coded ATCs.
AI-readable verification (optional, recommended)
For the test you just wrote, run Allure 3 in agent mode to get a markdown report you can read directly without parsing HTML:
bun allure:agent
Allure 3 lives as a devDep — bunx allure resolves to the local node_modules/.bin/allure, no global install required. Use this when:
- The Code subagent needs to confirm the test actually exercised the expected ATC (the markdown summary lists each
@atc('TICKET-ID') block + its status).
- You want a quick scope check before opening Phase 3 — Review.
- You are debugging a fixture/locator mismatch and want a structured failure read instead of a raw stack.
For human review of the same run, switch to:
bun allure:run
bun allure:open
See regression-testing for CI / suite-level reporting (bun allure:generate, bun allure:watch).
Phase 3 — Review
Use the dispatch defined in §Subagent Dispatch Strategy: Parallel (3 simultaneous Verifiers). Full briefings in references/review-checklists.md §Parallel verification dispatch.
Run the review checklist on the new/modified files. Treat every failed item as a blocker. A clean review is the merge gate. See references/review-checklists.md for the full lists (E2E and API have overlapping but distinct checklists).
Optional adversarial gate — for high-risk changes (new fixtures, shared Page/Api base modifications, refactors touching multiple ATCs), invoke /judgment-day before commit. Runs two blind judges in parallel against the diff and only approves when both agree. See .claude/skills/judgment-day/SKILL.md. Not invoked automatically — user opts in per ticket.
Progress checkpoint + Archive: after Phase 3 returns ACCEPT (all 3 Verifiers exit 0), the orchestrator appends ## Phase 3 — Review — <ts> with status: completed, next: stop to .session/test-automation/<scope>/progress.md, then runs Archive per agentic-qa-core/references/session-management.md §8: moves .session/test-automation/<scope>/ to .session/.archive/<YYYY-MM-DD>-test-automation-<scope>/ (two-file dir preserved) and calls mem_session_summary including the archive path. On REJECT, archive does NOT run — the working directory stays for debug.
Git & TMS handoff (sdet integration-trunk suites)
This skill stops at a clean local review. It does not create branches, push, or open PRs — that is /git-flow-master's job. When the repo's git strategy is sdet (the standing mode for chained test-automation suites), each ticket flows through the per-ticket loop in .claude/skills/git-flow-master/references/sdet-integration-trunk.md:
- The Phase 3 ACCEPT gate (3 Verifiers green:
test / types:check / lint:check) is the skill's local validation gate. Under sdet it must pass on both the local and staging environments before push — re-run the suite against each (active_env per .agents/project.yaml). The Verifiers are local-only; Sanity CI on the branch is owned by /git-flow-master + /regression-testing, never by this skill.
- After ACCEPT, surface the explicit handoff — "Local gate green. Ready for
/git-flow-master: cut test/{KEY}-{slug} from the integration trunk, push, Sanity-CI, PR into the trunk, merge --no-ff." Do not auto-invoke git operations.
- Append the Git Ledger line to the suite's
progress.md after each branch action (orchestrator-written, append-only) so a resuming session knows how the trunk was left: trunk name + SHA, last ticket merged, pending tickets, sync-gate / final-PR state. Schema in ../agentic-qa-core/references/session-management.md §7 "The Git Ledger"; what-to-write detail in .claude/skills/git-flow-master/references/sdet-integration-trunk.md §Resume.
- TC lifecycle anchors to the ticket-branch PR, not the final
trunk → main PR: TCs → In Review when the ticket PR opens into the trunk; they flip to Automated only after the final suite PR merges to main and CI is green there. Execute transitions via /test-documentation + [ISSUE_TRACKER_TOOL]; cross-check status names against .agents/jira-workflows.json. Merging into the trunk is NOT "Automated".
Fixture selection (inline — load-bearing every invocation)
The fixture you pick determines whether a browser opens. Wrong fixture = slow API tests or missing UI context.
| Test type | Fixture | Browser opens? | Use when |
|---|
| API only (integration) | { api } | No (lazy) | Pure API testing. No UI needed. |
| UI only | { ui } | Yes | UI-focused testing. No backend setup via API. |
| Hybrid (UI + API setup) | { test } | Yes | Setup data via API, drive flow via UI, verify via API. |
| Reusable precondition chains | { steps } | Depends on steps used | 3+ ATCs repeated across 3+ files. |
Rules:
- Integration tests (
tests/integration/**) almost always use { api }.
- E2E tests (
tests/e2e/**) use { ui } if no API setup needed, otherwise { test }.
- Never request
{ ui } for a test that never interacts with the UI -- it opens a browser for nothing.
Gotchas (inline — the most common rejection reasons)
- ATC = complete test case, not a single click.
clickLoginButton() is not an ATC. loginWithValidCredentials(credentials) is. If the method is one-line-wrapping page.click(), delete it.
- TC Identity Rule: Precondition + Action = 1 TC. All expected results from the same precondition and same action are assertions of the same TC, not separate TCs. Do not split a TC across panels, endpoints, or UI sections.
- Equivalence Partitioning. Same expected output = one parameterized ATC. Three ATCs all returning HTTP 401 for invalid login are wrong -- merge into one
loginWithInvalidCredentials(payload).
- ATCs do not call ATCs. ATCs are atomic. For reusable chains, use the Steps module (
tests/components/steps/*Steps.ts). Steps are NOT decorated with @atc.
- Locators inline. No
locators/*.ts files. Put the selector in the ATC. If the same locator is used in 2+ ATCs of the same component, extract it to a private readonly arrow function in the class -- not to a separate file.
- Helpers vs ATCs. A read-only GET is a helper (no
@atc, optionally @step). An action that changes state is an ATC (@atc('TICKET-ID')). A GET inside an ATC that verifies the action succeeded is fine -- but the GET alone is not an ATC.
- Fixed assertions go inside ATCs. Status code, required fields, URL redirect checks. Test-level assertions (flow outcomes) go in the test file.
- Max 2 positional parameters. 3+ parameters must use an object parameter (
fn(args: Args)). Named object parameters beat positional lists for maintainability and autocomplete.
- Import aliases are mandatory.
@api/, @ui/, @utils/, @variables, @TestContext, @schemas/. No relative imports (../../../). Lint will reject them.
- No hardcoded waits. Never
page.waitForTimeout(3000). Wait for a specific condition: waitForSelector, waitForResponse, waitForLoadState('networkidle'), or data-loaded="true" attributes.
- No retries by default.
retries: 0 in playwright.config.ts. If a test passes on retry, it is flaky, not passing. Investigate.
- Credentials from
.env, never hardcoded. LOCAL_USER_EMAIL / STAGING_USER_EMAIL and their passwords. Read via config.testUser from @variables.
- Each test generates its own data. No shared state between tests. Use
TestContext.generateUserData() or faker helpers for unique values.
- Ticket ID prefix in every
test(). Format: test('TICKET-ID: should {behavior} when {condition}', ...). The describe block may also include the ticket ID when the file is tied to a single ticket.
- One component per file, one file per feature. Components follow
{Resource}Api.ts or {Page}Page.ts. Test files follow {verb}{Feature}.test.ts (e.g., applyDiscount.test.ts, never discount.test.ts).
- Don't propose components or ATCs without consulting the manifest.
kata-manifest.json is the registry. Skipping it produces (a) duplicate Pages — proposing LoginPage when LoginPage.ts already exists; (b) duplicate ATC IDs — minting @atc('PROJ-90') twice; (c) missed reuse — creating getBookingById when BookingsApi.getById already does it. Always start the Plan phase by loading the manifest. The husky pre-commit gate enforces freshness; Critical Rule #12 in CLAUDE.md enforces consultation.
- Cross-cutting test-architecture decisions become ADRs, not plan-buried prose. When Plan or Code reveals a decision that is architectural AND hard to reverse — a fixture lifecycle reused across 3+ ATCs or 2+ tickets, a test-data-isolation contract, an auth-in-tests change, a flake-retry-policy shift, a Page-Object-vs-Screenplay move — promote it from
planning-playbook.md §2 "Architecture Decisions" to a standalone .context/ADR/ADR-NNNN-<slug>.md and leave a See ADR-NNNN backlink. Ticket-local choices stay in the plan. ADRs are append-only: supersede, never rewrite. See agentic-qa-core/references/adr-doctrine.md.
- Session-footer contract (mandatory at close). The final phase is not done until the two chat-facing blocks from
../agentic-qa-core/references/session-footer-contract.md are printed: (1) consolidated screenshot list — repo-relative paths, verified on disk, bug annotations first — plus in-flow surfacing of every capture's path the instant it lands; (2) Session Footer listing skills/MCPs/CLIs actually used + testing levels touched, with explicit "none" entries for expected-but-untouched levels. Framing for this skill: authoring. Multi-subagent sessions: each stage report carries the five footer fields (skills_loaded, mcps_used, clis_used, testing_levels_touched, screenshots_captured); the orchestrator compiles the footer ONCE at close. Chat only — never in a Jira comment or ATR body.
Minimal templates (inline — small, load-bearing)
KATA component signatures
export class UsersApi extends ApiBase {
constructor(options: TestContextOptions) { super(options); }
@step
async getUserById(id: string): Promise<[APIResponse, UserResponse]> {
return this.apiGET<UserResponse>(`/users/${id}`);
}
@atc('TICKET-ID')
async createUserSuccessfully(payload: UserPayload): Promise<[APIResponse, UserResponse, UserPayload]> {
const [response, body, sent] = await this.apiPOST<UserResponse, UserPayload>('/users', payload);
expect(response.status()).toBe(201);
expect(body.id).toBeDefined();
return [response, body, sent];
}
}
export class LoginPage extends UiBase {
constructor(options: TestContextOptions) { super(options); }
@atc('TICKET-ID')
async loginWithValidCredentials(data: LoginData): Promise<void> {
await this.page.goto('/login');
await this.page.locator('#email').fill(data.email);
await this.page.locator('#password').fill(data.password);
await this.page.locator('button[type="submit"]').click();
await expect(this.page).toHaveURL(/.*dashboard.*/);
}
}
Test file skeleton
import { test, expect } from '@TestFixture';
import usersData from '@data/fixtures/users.json';
test.describe('TICKET-ID: Validate discount codes', () => {
test('TICKET-ID: should apply percentage discount when code is valid', async ({ api }) => {
const order = await api.orders.createOrderSuccessfully(orderData);
const totals = await api.orders.getTotals({ orderId: order.id });
expect(totals.finalAmount).toBe(totals.baseAmount - totals.discountAmount);
});
});
Fixture registration (excerpt)
export class UiFixture extends TestContext {
readonly login: LoginPage;
readonly checkout: CheckoutPage;
constructor(options: TestContextOptions) {
super(options);
this.login = new LoginPage(options);
this.checkout = new CheckoutPage(options);
}
}
Quality gates (must pass before merge)
| Gate | Command | Must be |
|---|
| Tests pass | bun run test {path} | All green, zero retries used |
| Types | bun run types:check | No errors |
| Lint | bun run lint:check | No errors |
| Fixture registered | visual | Component is in ApiFixture / UiFixture / StepsFixture |
| ATC IDs linked | visual | Every @atc('X') matches a real TMS test case ID |
| Naming | visual | Files PascalCase for components, camelCase verb for test files |
| Session footer | chat | Session footer + consolidated screenshot list printed in chat per session-footer-contract (never in a Jira comment) |
Anti-patterns — NEVER do these
T1. NEVER auto-generate tests for TCs that /test-documentation flagged as Deferred or Manual — only Candidate (to_be_automated) verdicts proceed to automation. Skipping the ROI verdict produces flaky, low-value suites.
T2. NEVER skip the Plan phase. Even for a "simple" regression test, write spec.md / automation-plan.md (or the per-ATC plan under .context/PBI/epics/EPIC-<KEY>-<slug>/test-specs/<scope>/) BEFORE writing any test code. Plan → Code → Review is non-negotiable.
T3. NEVER collapse the KATA layers (TestContext / ApiBase + UiBase / Domain Api+Page+Steps / Fixture). Full doctrine in references/kata-architecture.md. Tests that flatten layers are rejected at Review.
T4. NEVER call one ATC from inside another ATC. ATCs are atomic mini-flows. Reusable chains live in the Steps module (tests/components/steps/*Steps.ts), which is NOT decorated with @atc.
T5. NEVER use relative imports (../../../). This repo uses path aliases (@api/, @ui/, @schemas/, @utils/, @TestContext, @variables, @TestFixture). Lint rejects relative paths.
T6. NEVER hardcode credentials. Read from .env via config.testUser from @variables (LOCAL_USER_* / STAGING_USER_*). Never inline a password, token, or API key in a spec, fixture, or test data file.
T7. NEVER hardcode customfield_NNNNN in spec files, test data, or test config. Resolve Jira fields via {{jira.<slug>}} against .agents/jira-fields.json + .agents/jira-required.yaml so test code survives workspace rotations.
T8. NEVER mix test code and product code in the same PR. Test PRs follow the test/* branch convention with title format {type}({ISSUE-KEY}): {description} — see .claude/skills/git-flow-master/references/pr-test-automation.md. Under the sdet strategy, adjacent non-test work never rides a test/* ticket branch either — it goes on a Plus Branch (docs/*/chore/*/fix/* → integration trunk). See .claude/skills/git-flow-master/references/sdet-integration-trunk.md.
Which reference to read
Not every invocation needs every reference. Load the specific file when the task matches.
- KATA architecture, fixture selection, ATC rules, Steps module mechanics →
references/kata-architecture.md
- TypeScript conventions (params, imports, types, errors, DRY by layer) →
references/typescript-patterns.md
- Naming, tagging, folder structure, anti-patterns, quality gates →
references/automation-standards.md
- Writing a Playwright
Page component, locator strategy, data-testid rules, UI waits → references/e2e-patterns.md
- Writing an
Api component, OpenAPI type facades, HTTP helper usage, schema imports → references/api-patterns.md
- Designing test data (Discover → Modify → Generate), fixtures JSON, faker →
references/test-data-management.md
@atc / @step decorators, NDJSON results, TMS sync mechanics → references/atc-tracing.md- Writing the Plan (module / ticket / ATC scopes and templates) →
references/planning-playbook.md
- Running the review checklist (E2E or API) →
references/review-checklists.md
- Configuring Playwright, CI integration, projects, sharding →
references/ci-integration.md
- Session resume contract, plan.md/progress.md schemas, archive policy, Engram per-phase checkpoint →
../agentic-qa-core/references/session-management.md (Phase 0 + Phase 1 + Archive of this skill)
Tool resolution: use [AUTOMATION_TOOL] for browser work (Playwright CLI or MCP — load /playwright-cli when available), [API_TOOL] for OpenAPI exploration, [DB_TOOL] for verifying test data in the database, [TMS_TOOL] for TMS sync (load /xray-cli when available), [ISSUE_TRACKER_TOOL] for ticket work. Split the issue-tracker access by operation: detailed reads of a Story (ACs, ATP, dev implementation-plan, custom fields) → bun run jira:sync-issues get <KEY> --include-comments (or jql "<query>") then read the synced .md — NEVER acli workitem view for custom fields; writes (comment automated-test status back to the Story, transitions) → /acli; trivial summary/status/key-list lookups → /acli workitem view/search is fine. See agentic-qa-core/references/acli-integration.md §"Reads vs writes". Resolve tags via the project's CLAUDE.md Tool Resolution table.
Quick reference
bun run test <path>
bun run types:check
bun run lint:check
bun run kata:manifest
git add kata-manifest.json
bun run kata:manifest:check
cp .env.example .env
bun run api:sync
