agentic-playwright type-safety.instructions.md

Type Safety

Critical

• NEVER use any. Use explicit types, Zod-inferred types (zOutput<typeof ...>), or unknown at boundaries.
• NEVER use as T or as unknown as T to silence the type-checker. If you genuinely need to cross a type boundary, validate first (Schema.parse(...)) and let Zod produce the typed result.
• ALWAYS define API schemas with z.strictObject(). z.object() silently strips unknown keys and hides contract drift.
• ALWAYS prefer Zod 4 top-level validators (z.uuid(), z.email(), z.url(), z.int(), z.enum(E)) over the deprecated chained forms (z.string().uuid(), z.string().email(), etc.).
• ALWAYS assert API responses with the exact pattern expect(SchemaName.parse(body)).toBeTruthy();. Schema.parse(body) on its own is not enough.
• ALWAYS specify explicit return types on exported and public functions (Promise<void>, Promise<UserResponse>, Locator, string, etc.).
• Access process.env.* with ! (guaranteed at runtime) or ?? (with a safe fallback). Never let string | undefined leak into downstream code.
• Build response schemas directly from the documented contract. Define each field — including the response envelope (success / message / data / errors or whatever the API uses) — explicitly per endpoint, exactly as the OpenAPI / Swagger spec describes. Do not invent factories or helpers that hide the envelope. If an envelope is genuinely repeated across many endpoints in one domain, extract a per-domain shared z.strictObject definition (e.g. fixtures/api/schemas/{area}/_envelope.ts) and compose with .extend(...) — but only after the repetition is real and observed.

Schema Location

fixtures/api/schemas/
├── {area}/        ← App-specific schemas (user, product, etc.) — run `ls fixtures/api/schemas/` to find the real subdirectory
│   └── userSchema.ts
└── util/          ← Shared error response schemas
    └── errorResponseSchema.ts

Instructions

Phase 1: Rule out any and unsafe casts