Enums

Enums

Critical

• Convention: TypeScript enum — the scaffold uses the language construct enum, not as const object literals. Stay consistent.
• Enum name: PascalCase (e.g., Messages, ApiEndpoints, Roles, StorageStatePaths).
• Enum member: SCREAMING_SNAKE_CASE (e.g., LOGIN_SUCCESS, CURRENT_USER, APP).
• Location: app-defined strings go in enums/{area}/*.ts; cross-app constants go in enums/util/*.ts. Do not invent a new top-level folder.
• JSDoc: every enum declaration must have a JSDoc comment describing what the enum groups.
• No hardcoded repeat strings. Any string used in more than one place — endpoint paths, UI messages, roles, storage-state paths — must live in an enum and be imported.
• Message values must match the real app. For enums that mirror UI text (error messages, success messages, validation text), the string must be captured via playwright-cli from the live app, not guessed.
• Edits to existing enum values go through refactor-values. Renaming a key or changing a value cascades through tests, page objects, and schemas.

File Locations

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

Instructions

Phase 1: Decide if the value belongs in an enum

Use this decision table. Each row points to the canonical home — use it to prevent enums/ from overlapping with config/ or test-data/static/.

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

Phase 2: Pick the home — new file or extend existing

Prefer extending an existing enum file within the same domain over creating a new file. The goal is to keep related constants together so consumers have one predictable import per domain.

• If a value fits into an existing enum (e.g., a new error message belongs in Messages), add it there.
• If the domain is genuinely new (e.g., a checkout domain that warrants its own file), create enums/{area}/checkout.ts and add one or more enums to it.
• Shared constants that apply across all apps go in enums/util/*.ts.

Phase 3: Name the enum and its members

• Enum name — PascalCase, singular or plural per readability (Messages, ApiEndpoints, Roles, StorageStatePaths).
• Enum member key — SCREAMING_SNAKE_CASE.
• Enum member value — the actual string used by the app (exact case, exact punctuation).

Correct:

export enum ApiEndpoints {
    LOGIN = '/api/users/login',
    CURRENT_USER = '/api/users/me',
}

Incorrect:

Phase 4: Verify message values against the real app

When the enum mirrors UI text (error messages, success messages, validation text, button labels, page titles), the string value must come from observing the live application — not from assumptions, design specs, or guesses.

Workflow:

1. Read the playwright-cli skill (.claude/skills/playwright-cli/SKILL.md).
2. Run playwright-cli to trigger the relevant action in the app.
3. Capture the exact rendered text (case, punctuation, whitespace).
4. Encode it as the enum value.

If the app is unavailable, add the value with a // FIXME: unverified comment and flag it for confirmation once exploration is possible. Do not ship unverified message values.

Phase 5: Add JSDoc and export

Every enum declaration gets a JSDoc comment describing the group:

/** Common UI messages displayed to the user */
export enum Messages {
    LOGIN_SUCCESS = 'Successfully logged in',
    LOGIN_ERROR = 'Invalid email or password',
}

Re-use the pattern from enums/app/app.ts. The file itself may also carry a top-level JSDoc with an @example block (as the existing enums/app/app.ts does) when useful.

Phase 6: Editing existing enum values

When you need to change an enum member's string value or rename a member key, the change cascades through tests, page objects, API schemas, and data-driven loops.

Read the refactor-values skill (.claude/skills/refactor-values/SKILL.md) before touching an existing enum. It owns the impact-analysis and cascading-update workflow.

Examples