common-tasks

AI Prompt Templates for Agentic Playwright

Codegen sub-router. Owns prompt templates per artifact type and the post-generation verification checklist. Plugs into ai-native-workflow Phase 2 (Route) for codegen intents.

For the 8-phase workflow see ai-native-workflow/SKILL.md. For worked examples and troubleshooting see this skill's references/.

Critical

These rules are unique to template usage. All other rules (selectors, waits, types, Zod strictness, response validation, tags, fixtures, JSDoc, no-XPath, no-hardcoded-strings, etc.) live in the CLAUDE.md Constitution and the leaf skills (api-testing, page-objects, selectors, test-standards, data-strategy, type-safety, fixtures, enums). Re-read the Constitution + the matching leaf skill's Critical block before generating from any template here.

• Resolve {area} first. Every template contains {area} as a placeholder. Run the matching ls (ls pages/, ls tests/, ls fixtures/api/schemas/, ls test-data/factories/, ls test-data/static/, ls enums/) and substitute the real folder name before filling the template. Do not guess.
• Templates are starters, not substitutes. Each template is a 10-15 line scaffold. The leaf skill listed for the category owns the deep rules — load it and follow it end-to-end. Never reimplement a leaf skill's rules inline in your prompt.
• Walk the verification checklist (below) after generating. It is the canonical post-codegen audit; the leaf skills point here for it.

Instructions

Phase 1: Identify the task category and resolve paths

Match the user's request to one row, then run the ls commands the row's templates need.

Category	Template section	Specialized skill(s)	ls to run before filling
Page object / component	Page Object Tasks	page-objects, selectors, playwright-cli	ls pages/
Functional / E2E test	Test Tasks	test-standards, data-strategy	ls tests/, ls test-data/factories/
API test	Test Tasks → Add API Test	api-testing, test-standards	ls tests/, ls fixtures/api/schemas/, ls enums/
Zod response schema	API Schema Tasks	api-testing, type-safety	ls fixtures/api/schemas/
Data factory	Data Factory Tasks	data-strategy, type-safety	ls test-data/factories/
Static test data	Data Factory Tasks → Static Test Data	data-strategy, api-testing	ls test-data/static/
Fixture (POM / helper)	Fixture Tasks	fixtures, helpers	(no path placeholder)
UI component	Component Tasks	page-objects, selectors	(no path placeholder)

Phase 2: Select and customize the matching prompt template

Open the theme file for your category from the Prompt Templates index below, copy the block, and replace every [PLACEHOLDER] and every {area} with concrete values. Leave no unreplaced placeholders in the final prompt.

Phase 3: Load the specialized skill for the deep rules

The templates intentionally stay shallow. When the task needs more than the template's bullets — full status-code coverage, selector exploration rules, fixture composition patterns — load the specialized skill listed in Phase 1 and follow it end-to-end. Do not reimplement that skill's rules inline. Re-read the CLAUDE.md Constitution + the leaf skill's Critical block before writing code.

Phase 4: Verify with the checklist, then run the affected tests

Walk every box. Then run the affected tests; on red, load debugging.

Verification Checklist

After generating code, confirm each box:

• Imports are from fixtures/pom/test-options.ts (never @playwright/test in specs)
• Paths, credentials, and endpoints come from process.env.* and enums/{area}/* — nothing hardcoded
• Locators use getByRole / getByLabel / getByTestId — no XPath
• No any types
• No hard waits (waitForTimeout)
• No JSDoc on locator getters/methods (JSDoc only on action methods)
• Tests use test.step with Given/When/Then structure
• Each test has exactly ONE tag from @smoke, @sanity, @regression, @e2e, @api, @destructive (never @functional, never multiple)
• Tags live on individual tests, not on test.describe() blocks
• Tests that mutate shared/global state (locale, permissions, roles, guest access, feature flags, global settings) are tagged only @destructive; tests that create + clean up only their own data keep their importance tag
• Any state-mutating test (destructive or isolated) has an afterEach/afterAll hook that reverts what it wrote
• Happy-path test data uses factories; curated invalid values come from test-data/static/util/ or test-data/static/{area}/
• Zod schemas use z.strictObject() — never z.object()
• API response validation uses expect(SchemaName.parse(body)).toBeTruthy();
• API tests with request bodies include empty-body + per-field omission + per-field invalid-type for...of loops (universal arrays imported from test-data/static/util/invalid-values.ts)
• Coverage audit: Every status code in the OpenAPI spec has a matching test (or test.skip + // FIXME)
• Path parameter tests: Endpoints with path params have the invalid-format data-driven loop
• 405 tests: At least one unsupported HTTP method test per endpoint
• Auth matrix: Endpoints with security have both 401 (no token) and 403 (wrong role) tests
• Behavior mismatches: Any divergence from spec uses test.skip + // FIXME: <ticket-url>, never silent omission
• No explore-only or throwaway test files committed

Run the affected tests (mandatory)

npx playwright test tests/{area}/[type]/[name].spec.ts   # specific file
npx playwright test --grep @smoke                        # by tag
npm test                                                 # all non-destructive

Failure protocol: Read the error → load debugging (failure-mode taxonomy + right Playwright tool per failure: UI Mode, Trace Viewer, Inspector, HTML report) → fix the root cause (no try/catch on expect, no timeout bumps, no silent .skip) → re-run; for flake fixes, 5x consecutively.

Prompt Templates

Split by theme under templates/ so the agent loads only the slice it needs — open the file matching your Phase 1 category, copy the block, and replace every [PLACEHOLDER] and {area} with concrete values.

• Page object templates — new page object (with / without exploration), add locators, add action method
• Test templates — functional, E2E, data-driven, and API tests
• API schema templates — Zod schema from docs, fallback capture, add fields
• Data templates — Faker factory and static test data
• Fixture templates — page-object fixture, helper fixture, fixture category
• Component templates — reusable UI component

See Also

• CLAUDE.md — Constitution (MUST/SHOULD/WON'T tables) is the safety floor for every artifact generated from a template here.
• ai-native-workflow — owns the 8-phase workflow; Phase 2 routes codegen intents to this skill.
• api-testing — deep rules for API tests + schemas; load before using Add API Test or Create a New Zod Schema templates.
• page-objects, selectors, playwright-cli — the UI authoring chain; load before using Page Object Tasks templates.
• test-standards — spec structure, tagging, web-first assertions, data-driven loops; load before using any Test Tasks template.
• data-strategy — factory + static-data three-tier rule; load before using Data Factory Tasks.
• fixtures, helpers — DI patterns and helper-fixture promotion; load before using Fixture Tasks.
• type-safety — Zod 4 validators + the expect(Schema.parse(body)).toBeTruthy() rule; load before any schema work.
• debugging — load on Phase 4 verification red.
• refactor-values — load when a template would change an existing enum value or static-data row.
• references/examples.md — three end-to-end multi-skill chains using the templates.
• references/troubleshooting.md — common pitfalls when filling templates and how to fix.