agentic-playwright helpers.instructions.md

Helpers

Critical

• Helpers are plain functions. No Playwright fixture lifecycle — no use(), no base.extend. If you need setup → use(data) → teardown, it's a fixture, not a helper (see the fixtures skill).
• App-specific logic lives in helpers/{area}/ (e.g. helpers/app/). Generic utilities live in helpers/util/.
• ALWAYS add JSDoc with @param and @returns on every exported helper.
• ALWAYS specify explicit return types (Promise<void>, string, etc.). No implicit any.
• NEVER hardcode URLs, credentials, or tokens. Read env-driven values from process.env.* (see the config skill). Use enums/{area}/* for endpoint paths and storage-state paths.
• ALWAYS validate API responses inside helpers with the mandatory pattern expect(SchemaName.parse(body)).toBeTruthy(); — identical to the api-testing Critical rule.
• Function naming: camelCase verbs (createAppStorageState, setUserAccessToken, formatDate, parseCurrency).
• Do not promote a helper to a helper fixture unless the same setup/teardown is copy-pasted across 3+ spec files and needs guaranteed lifecycle (see the api-testing skill, Phase 8 rule of thumb).
• Mutating process.env from a helper is a narrow exception, not a general pattern. It is acceptable only for auth-bootstrap helpers that publish a token (e.g. writing process.env.ACCESS_TOKEN inside a login helper). Do not copy the env-mutation pattern into other helpers — return values through the function signature instead.

File Locations

{area} is a placeholder. Before creating or referencing any path below, run ls helpers/ to discover the real subdirectory names in this repo (e.g., front-office, back-office) and use those instead.