pw-kit

API testing patterns for Playwright + TypeScript — resource class pattern (HTTP wrappers extending BasePage, domain folders mirroring REST namespaces, typed payload builders), the ApiListener pattern for capturing real responses by stateKey without mocking, optional SQL/stored-procedure bridge for test-data setup, and TOTP-based MFA enrollment. Use when seeding test data via API, asserting on API responses without mocking, building HTTP wrapper classes, capturing network responses during UI tests, or setting up test users with MFA.

Web-first assertion patterns for Playwright + TypeScript — always await expect(locator).toXxx() (never snapshot-style expect(await locator.textContent())), never page.waitForTimeout, never waitForLoadState('networkidle'), expect.soft for supplementary checks, expect.poll for non-locator values, waitForResponse set up BEFORE the triggering action. Use when writing assertions, fixing flaky waits, debugging timing issues, removing hardcoded sleeps, asserting on API responses, or reviewing test assertion code.

Reference for the playwright-cli command-line tool — the verify-before-coding companion for Playwright + TypeScript test development. Covers the discovery workflow (open → snapshot → click/fill → emit locator code), API response verification via run-code, named browser sessions for multi-user tests, storage state save/load, tracing, and request mocking. Use when writing tests where element testids or interactions are uncertain, when verifying API response field names before assertions, or when debugging a test by replaying it interactively.

Convert a developer feature ticket into lean, ticket-ready Gherkin test cases for paste into a QA ticket. Produces 1 main success scenario + 2-4 edge cases max, merges near-identical data variants into one case with annotation, flags ambiguity inline with [QUESTION:] tags. Output is pure ticket-ready text — no code, no file paths. Use when user invokes /pw-kit:create-test-cases, says they have a dev card without a QA card yet, asks to "draft test cases", "write Gherkin scenarios from this feature", or wants to prepare QA scope before implementation.

Systematic 6-phase workflow for investigating and fixing failing Playwright tests. Classifies the root cause as app bug (test.fail + defect report), broken test (test.fixme + fix-me task), or flaky test (fix timing/data/state root cause). Uses trace viewer, app source code grep, and live reproduction with playwright-cli. Use when user invokes /pw-kit:fix-test, asks to "fix this failing test", "investigate test failure", "debug a test", or shares a test that's failing.

Central fixture pattern for Playwright + TypeScript test automation — single base-pages-fixture.ts file that pre-wires every page object, the browserPage root fixture (test-scoped page + worker-scoped browser), alphabetical ordering rule, import-via-path-alias pattern, and Pages interface for type safety. Use when adding a new page object to the fixture registry, when fixing 'not a function' errors from wrong fixture dependencies, when test files have lots of manual page-object instantiation, or when reviewing fixture registration order.

Patterns for interacting with form controls in Playwright + TypeScript — typeDateValue for date pickers (never fill or pressSequentially), relative-year variables instead of hardcoded dates, idempotent toggleSwitch, filterSingleSelect for dropdowns, save method variants (save/saveAndClose/saveAndConfirm), and required-field validation. Use when writing form interactions, working with date pickers, dropdowns, switches, checkboxes, when tests have flaky date input behavior, or when reviewing form-related test code.

Bootstrap a complete Playwright + TypeScript test automation project from scratch. Scaffolds folder structure (pages/, tests/, api/, modals/, data/), writes all configs (playwright.config.ts, tsconfig.json, .eslintrc, .prettierrc, .env template), generates base class skeletons (BasePage, BaseGridPage, BaseEditPage), creates the central fixture registry (base-pages-fixture.ts), and seeds example tests demonstrating the patterns. Use when user invokes /pw-kit:init, says they want to "start a new Playwright project", "scaffold playwright tests", "set up Playwright with these conventions", or asks how to initialize a Playwright + TypeScript repo.

Playwright + TypeScript locator conventions — strict priority ladder (getByTestId first, then role/label, then chained, then class/id, then text, CSS/XPath as last resort), data-testid naming convention, parameterized locators, filter/narrow patterns, and anti-patterns. Use when writing or reviewing locators in page objects, when choosing how to target an element, when fixing brittle CSS/XPath selectors, when a test has 'resolved to N elements' errors, or when reviewing test code.

Guided workflow for creating a new Playwright + TypeScript test from a ticket. Walks through context gathering, app source analysis, existing test inventory, live discovery with playwright-cli or Playwright MCP, proposal gate before writing code, implementation collaboration, and mandatory gap analysis. Use when user invokes /pw-kit:new-test, asks to "write a new test", "create a test for TICKET-NNNNN", "implement test from ticket", or mentions a QA/feature ticket needs testing.

Page Object Model architecture for Playwright + TypeScript — base class hierarchy (BasePage, BaseGridPage, BaseEditPage), decision tree for which base to extend, gridPrefix constructor pattern, POM authoring rules (plural for grids, singular for edits, file naming, no redundant base methods). Use when creating a new page object, deciding which base class to extend, adding methods to a page object, choosing between adding to base vs subclass, or reviewing POM structure.

Pre-PR quality and convention check for Playwright + TypeScript test changes. Walks through 13 categories — commit messages, naming, locators, dates, assertions, cleanup, file standards, page objects, parallel safety, branch state, gap analysis, ticket process. Reports each violation as file + line + rule + suggested fix. Use when user invokes /pw-kit:pre-pr, asks to "check my changes before PR", "review my test changes", "is this ready to ship", or before opening a pull request.

Test data management patterns for Playwright + TypeScript — decision framework for in-test creation vs precreated DB seed vs read-only fixtures, try/finally cleanup with cleanupNeeded flag (never try/catch), unique-data identifiers for parallel safety (randomNumber, randomElement, getDateNDaysFromNow), step named exactly 'Cleanup'. Use when designing test data strategy, choosing between API setup and UI setup, adding cleanup to a test, fixing test data collisions in parallel runs, or reviewing test data handling.

Test file structure and naming for Playwright + TypeScript — Gherkin test.step (Given/When/Then/Cleanup), ticket-prefixed naming, file size limits (50 tests / 1200 lines), failure classification (test.fail / test.fixme / test.skip), try/finally cleanup pattern, no functions in test files, and parallel-safety rules. Use when writing a new test, naming a test or describe block, structuring test.step calls, classifying a failing test, refactoring oversized test files, or reviewing test organization.