Type Safety

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

The TypeScript project is "strict": true. That configuration exists to surface bad types; don't work around it.

// FORBIDDEN
const data: any = await response.json();
function process(input: any): any {
    /* ... */
}
const user = raw as UserResponse;
const user = raw as unknown as UserResponse;

// CORRECT
const raw: unknown = await response.json();
const user = UserResponseSchema.parse(raw); // Zod validates + types
function process(input: unknown): ProcessedResult {
    /* ... */
}

Rules:

• unknown is the right type at a boundary (network, file read, user input) — convert to a concrete type via Schema.parse(...).
• Inside a function body, every variable must have a concrete type (explicit or inferred from a typed source).
• as T is a red flag. If you see one, ask: "Can I parse with Zod here instead?" The answer is almost always yes.

Phase 2: Define the Zod schema

Use z.strictObject() and Zod 4 top-level validators. Build the response schema — including the envelope — directly from the OpenAPI / Swagger documentation. Each schema is a self-contained 1:1 mirror of the documented contract.

import { z } from 'zod/v4';
import type { output as zOutput, input as zInput } from 'zod/v4';

// 1. Define the domain schema with strict validation
export const UserSchema = z.strictObject({
    id: z.uuid(),
    email: z.email(),
    token: z.string().min(1),
    role: z.enum(['admin', 'user', 'guest']),
    avatar: z.url().optional(),
});

// 2. Wrap with the response envelope exactly as the spec describes it.
//    Spell every field out — no factory helper. If many endpoints in this
//    domain share the same envelope, extract a per-domain `_envelope.ts`
//    `z.strictObject` and compose with `.extend(...)` (only after the
//    repetition is real).
export const UserResponseSchema = z.strictObject({
    success: z.boolean(),
    message: z.string(),
    data: UserSchema,
    errors: z.unknown().nullable(),
});

// FORBIDDEN -- z.object() silently strips unknown keys
export const Schema = z.object({
    id: z.uuid(),
});

// CORRECT -- z.strictObject() rejects unknown keys at runtime
export const Schema = z.strictObject({
    id: z.uuid(),
});

Phase 3: Infer the TypeScript type from the schema

Zod 4 exposes two inference helpers. Pick based on whether you want the shape before or after transforms / defaults:

• zOutput<typeof Schema> — the type after parsing (defaults applied, transforms run). Use this for response types and 99% of schema consumers.
• zInput<typeof Schema> — the type before parsing (defaults optional, pre-transform values accepted). Use this for form payloads or request bodies where the caller may omit defaulted fields.

import type { output as zOutput, input as zInput } from 'zod/v4';

export type User = zOutput<typeof UserSchema>;
export type UserResponse = zOutput<typeof UserResponseSchema>;

// Example where Input and Output differ -- a schema with a default:
const SignupSchema = z.strictObject({
    email: z.email(),
    role: z.enum(['admin', 'user']).default('user'),
});

type SignupInput = zInput<typeof SignupSchema>; // { email: string; role?: 'admin' | 'user' }
type SignupOutput = zOutput<typeof SignupSchema>; // { email: string; role: 'admin' | 'user' }

If there are no .default(...) or .transform(...) calls, zInput and zOutput produce the same type — still prefer zOutput for clarity.

Phase 4: Validate at runtime with the mandatory assertion

API response validation uses the exact assertion pattern enforced across the scaffold:

import {
    UserResponse,
    UserResponseSchema,
} from '../../../fixtures/api/schemas/app/userSchema';
import { ApiEndpoints } from '../../../enums/app/app';

const { status, body } = await apiRequest<UserResponse>({
    method: 'GET',
    url: ApiEndpoints.CURRENT_USER,
    baseUrl: process.env.API_URL,
});

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

• The generic <UserResponse> gives compile-time safety on body.
• expect(SchemaName.parse(body)).toBeTruthy(); is the mandatory runtime check — not schema.parse(body) alone, not a bare SchemaName.parse(body) with no assertion.
• If the response is legitimately null (e.g., a 204 DELETE), assert expect(body).toBeNull() instead — do not call parse() on null.

This pattern is enforced in the api-testing Critical rule and repeated by helpers and test-standards. Any helper, fixture, or spec that calls apiRequest follows it.

Phase 5: Annotate function signatures

Always specify return types on public / exported functions. TypeScript can often infer them, but an explicit annotation documents the contract and surfaces breaking changes earlier.

// CORRECT
async submit(): Promise<void> { /* ... */ }
async getData(): Promise<UserResponse> { /* ... */ }
get submitButton(): Locator { /* ... */ }
export function formatDate(value: number | string): string { /* ... */ }

// AVOID -- return type missing
async submit() { /* ... */ }

Parameter types must also be explicit — never rely on noImplicitAny to rescue a missing annotation.