The Playwright Playbook — Bonus: Refactoring Schema Validation with Zod

// utils/schema-validator.ts — original (Part 4)

export interface TaskSchema {
  id: number;
  title: string;
  status: string;
  assignee: string;
  createdAt: string;
  updatedAt: string;
}

export function validateTaskSchema(task: unknown): task is TaskSchema {
  if (typeof task !== 'object' || task === null) return false;

  const t = task as Record<string, unknown>;

  return (
    typeof t.id === 'number' &&
    typeof t.title === 'string' &&
    t.title.length > 0 &&
    ['pending', 'in_progress', 'completed'].includes(t.status as string) &&
    typeof t.assignee === 'string' &&
    typeof t.createdAt === 'string' &&
    typeof t.updatedAt === 'string' &&
    !isNaN(Date.parse(t.createdAt as string)) &&
    !isNaN(Date.parse(t.updatedAt as string))
  );
}

export function validateTaskListSchema(tasks: unknown): tasks is TaskSchema[] {
  return Array.isArray(tasks) && tasks.every(validateTaskSchema);
}

❌ No error messages — just true/false. WHICH field failed? You don't know.
❌ The TaskSchema interface and the validation logic can silently drift apart.
❌ Adding optional fields, nested objects, or unions means hand-writing more checks.
❌ No reusable composition — every new entity needs its own validator from scratch.

npm install zod

// utils/schema-validator.ts — refactored with Zod
import { z } from 'zod';

// Define the schema ONCE — this is now the single source of truth
export const TaskSchema = z.object({
  id: z.number(),
  title: z.string().min(1, 'title must not be empty'),
  status: z.enum(['pending', 'in_progress', 'completed']),
  assignee: z.string(),
  createdAt: z.string().refine(
    (val) => !isNaN(Date.parse(val)),
    { message: 'createdAt must be a valid date string' }
  ),
  updatedAt: z.string().refine(
    (val) => !isNaN(Date.parse(val)),
    { message: 'updatedAt must be a valid date string' }
  ),
});

// Type is INFERRED from the schema — no separate interface to maintain
export type Task = z.infer<typeof TaskSchema>;

export const TaskListSchema = z.array(TaskSchema);

/**
 * Validates a single task. Returns true/false — same signature as before,
 * so existing test files using validateTaskSchema() don't need to change.
 */
export function validateTaskSchema(task: unknown): task is Task {
  return TaskSchema.safeParse(task).success;
}

/**
 * Validates a list of tasks. Same drop-in signature as Part 4.
 */
export function validateTaskListSchema(tasks: unknown): tasks is Task[] {
  return TaskListSchema.safeParse(tasks).success;
}

/**
 * NEW — Validates and returns the actual Zod errors when something fails.
 * This is what the original validator couldn't do at all.
 */
export function validateTaskSchemaDetailed(task: unknown) {
  const result = TaskSchema.safeParse(task);

  if (result.success) {
    return { valid: true as const, data: result.data };
  }

  // Human-readable list of exactly what failed and why
  const errors = result.error.issues.map(
    issue => `${issue.path.join('.')}: ${issue.message}`
  );

  return { valid: false as const, errors };
}

                      Hand-rolled (Part 4)     Zod (this bonus)
──────────────────    ──────────────────────   ──────────────────────
Lines of code          ~20                      ~20 (similar, but does more)
Error messages          None — just boolean      Field-level, human readable
Type source             Separate interface       Inferred from schema (z.infer)
Adding optional field   Manual undefined check   .optional() — one word
Nested objects          Painful, manual          .object({ ... }) — composable
Reusability             Copy-paste per entity     Schemas compose with .extend()
Drift risk               Interface vs logic        Single source of truth
                        can silently diverge

// tests/api/tasks-api.spec.ts — example using the new detailed validator
import { test, expect } from '../../fixtures/api.fixture';
import { validateTaskSchemaDetailed } from '../../utils/schema-validator';

test('GET /api/tasks/:id returns correct task — with detailed errors', async ({
  adminTaskApi,
}) => {
  const { task: created } = await adminTaskApi.createTask({
    title: 'Zod validation test task',
  });

  const fetched = await adminTaskApi.getTask(created.id);

  const result = validateTaskSchemaDetailed(fetched);

  if (!result.valid) {
    // If this fails, the test output tells you EXACTLY which field broke
    // e.g. "status: Invalid enum value. Expected 'pending' | 'in_progress' | 'completed', received 'done'"
    throw new Error(`Schema validation failed:\n${result.errors.join('\n')}`);
  }

  expect(result.data.title).toBe('Zod validation test task');

  await adminTaskApi.deleteTask(created.id);
});

🔴 Old validator failure:
  expect(validateTaskSchema(fetched)).toBe(true)
  Expected: true
  Received: false
  → You now have to manually inspect the response to find what's wrong

✅ Zod validator failure:
  Schema validation failed:
  status: Invalid enum value. Expected 'pending' | 'in_progress' | 'completed', received 'done'
  → You know immediately: the API started returning 'done' instead of 'completed'

// Reusable sub-schema
const AssigneeSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

// Compose it into the Task schema with .extend()
const TaskWithAssigneeSchema = TaskSchema.extend({
  assignee: AssigneeSchema, // overrides the string field with the nested object
});

// Or build a "create payload" schema that's a subset of fields
const CreateTaskPayloadSchema = TaskSchema.pick({ title: true, status: true });

// Or make fields optional for a PATCH payload
const UpdateTaskPayloadSchema = TaskSchema
  .pick({ title: true, status: true, assignee: true })
  .partial(); // every field becomes optional

Hand-rolled validator makes sense when:
  ├── You have one or two simple schemas
  ├── You want zero dependencies
  └── You're teaching the underlying concept (which is why Part 4 used it)

Zod makes sense when:
  ├── You have multiple related schemas (Task, CreateTaskPayload, UpdateTaskPayload...)
  ├── You want error messages that actually help you debug
  ├── Your schemas need composition (nested objects, nullable, optional, unions)
  └── You're building this for a real production test suite

playwright-playbook/
├── utils/
│   └── schema-validator.ts    ← refactored (this bonus), same exports
├── package.json                ← added "zod" dependency