Helpers

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.

Instructions

Phase 1: Classify what you're adding

Use this table. The correct criterion is "does this need the Playwright fixture lifecycle?" — not "is this used in setup or in tests?". A plain utility like formatDate is a helper even though it's called from inside tests.

If the need fits none of these rows, stop and ask. Do not invent a new location.

Phase 2: Pick the home — app-specific or utility

• helpers/{area}/ — logic that only makes sense for the app under test: authentication flows, storage state creation, data seeding, app-specific request composition.
• helpers/util/ — logic that's reusable across apps or projects: date formatting, string manipulation, retry logic, parsing utilities.

Prefer extending an existing file (createStorageState.ts, util.ts) over creating a new one when the function belongs to the same domain. Create a new file only when the domain is genuinely new.

Phase 3: Define the function signature, types, and JSDoc

Every exported helper must declare:

• An explicit return type (Promise<void>, string, UserResponse, etc.). No implicit any.
• Named parameters with explicit types.
• A JSDoc block with a description, @param for every argument, @returns, and — when useful — an @example block.

Pattern:

/**
 * Creates and saves the browser storage state after successful login.
 * @returns {Promise<void>} Resolves when storage state is saved.
 */
export async function createAppStorageState(): Promise<void> {
    // implementation
}

Phase 4: Read env-driven values from process.env.*

Helpers never hardcode URLs, credentials, or tokens. Read from process.env.* and use enums for endpoint paths / storage-state paths:

import { ApiEndpoints, StorageStatePaths } from '../../enums/app/app';

// CORRECT
baseUrl: process.env.API_URL,
url: ApiEndpoints.LOGIN,
body: { email: process.env.APP_EMAIL, password: process.env.APP_PASSWORD },
await context.storageState({ path: StorageStatePaths.APP });

// FORBIDDEN
baseUrl: 'https://api.example.com',
url: '/api/users/login',

See the config skill for sources of truth and the enums skill for paths.

Phase 5: If the helper makes API calls, validate with Zod

The mandatory API response-validation pattern from api-testing applies equally inside helpers:

const { status, body } = await apiRequest<UserResponse>({
    method: 'POST',
    url: ApiEndpoints.LOGIN,
    baseUrl: process.env.API_URL,
    body: { email: process.env.APP_EMAIL, password: process.env.APP_PASSWORD },
});

expect(status).toBe(200);
expect(UserResponseSchema.parse(body)).toBeTruthy();

Rules:

• The generic <UserResponse> gives compile-time safety on body.
• expect(SchemaName.parse(body)).toBeTruthy(); is the exact assertion — not schema.parse(body) alone.
• If the response can legitimately be null (e.g., a 204 DELETE), assert expect(body).toBeNull() instead.

Phase 6: Consume the helper

Call the helper from the right context — helpers have no lifecycle of their own, so where you call them matters:

• Auth bootstrap (tests/{area}/auth.setup.ts) — app-login helpers run once before the main test suite to produce storage state and/or tokens. The scaffold ships a demo implementation in helpers/app/createStorageState.ts; adapt or replace it to match your app's auth flow.
• Inside a test / beforeEach / afterEach — utility helpers freely, API helpers when they do self-contained work.
• Inside a fixture — a fixture can call a helper as part of its setup/teardown. The fixture owns the lifecycle; the helper stays stateless.

Auth-bootstrap helpers that publish a token via process.env.* (e.g. the demo setUserAccessToken in the scaffold) are the one place env mutation is acceptable. Every other helper must return its results through the function signature.

Examples

Example 1: Add a utility helper

User says: "Add a helper that parses a currency string like $1,234.56 into a number so tests can assert on cart totals."

Actions:

1. Phase 1 — Pure function, no lifecycle → helper.
2. Phase 2 — Generic, reusable across apps → helpers/util/util.ts (extend the existing file).
3. Phase 3 — Signature: export function parseCurrency(value: string): number, with JSDoc + @param + @returns.
4. Phase 6 — Consume inside tests: expect(parseCurrency(await cart.totalText())).toBe(1234.56);.