The Playwright Playbook — Bonus: Refactoring Schema Validation with Zod

"The best content ideas come from the comments, not the outline."

In Part 4, we built utils/schema-validator.ts — a hand-rolled function that checks whether an API response actually matches the Task shape we expect. Type-correct fields, valid status enum, valid date strings. The works.

A reader, Misha, asked a great question in the comments: "What do you think about using Zod for schema validation?"

Fair challenge. The manual validator works — but it's not how most production codebases would do this in 2026. So here's the honest comparison, side by side, with the refactor. 🎯

This is a focused bonus — just the schema validator. Everything else from Part 4 (TaskApiClient, AuthApiClient, the test files) stays exactly as it was.

🔍 Where We Left Off — The Original Validator

Here's what we built in Part 4:

// 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);
}

This works. It's type-safe. It does the job.

But it has real limitations once your schemas grow past one entity:

❌ 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.

Let's fix all four with Zod. 👇

📦 Installing Zod

npm install zod

That's the only new dependency. No config changes needed.

🔧 The Refactored Validator

// 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 };
}

Notice: validateTaskSchema and validateTaskListSchema keep the exact same function signature as Part 4. Every test file that imports them — tasks-api.spec.ts, graphql-api.spec.ts, api-ui-chain.spec.ts — works unchanged. Zero refactor needed in the test suite. ✅

🆚 Side-by-Side Comparison

                      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

✅ Using the Detailed Errors in Tests

This is where Zod actually pays off — when a test fails, you know exactly why.

// 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);
});

Compare the failure messages:

🔴 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'

That second one is the entire argument for Zod. When this fails in CI at 2am, you don't need to reproduce it locally to know what broke. 🔥

🧩 Bonus — Composing Schemas (Something the Old Validator Couldn't Do)

This is where Zod really separates itself. Say we want a schema for a task that includes nested assignee details instead of just a string:

// 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

Try doing .pick(), .partial(), or .extend() with a hand-rolled type-guard function. You'd be rewriting the whole validator by hand every time. With Zod, it's one line. ✅

🤔 So... Was the Hand-Rolled Validator Wrong?

Not wrong — just simpler than what you'd want at scale.

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

For a real framework — which is what we've built across all 8 parts — Zod is the better long-term choice. Worth the one dependency. 🎯

📁 What Changed in the Project Structure

Just one file modified. Everything else from Parts 1–8 stays exactly as built:

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

No test files needed to change. No fixtures needed to change. That's the benefit of keeping the function signatures identical during the refactor. ✅

🔖 Before You Go

Thanks to Misha for the question that sparked this. This is exactly the kind of comment I want more of — keep them coming. 🙌

If there's a part of the framework you'd want refactored, extended, or challenged — drop it below. The next bonus post might be your idea.

Drop a comment below 👇

Are you using Zod already, or is this your first look at it?
What other library would you want to see swapped in — Yup? Joi? io-ts?
Anything else from the series you'd want a deep-dive bonus on?

Faizal Shaikh | Senior Automation Engineer | Playwright & AI Testing
Connect with me on LinkedIn

推荐订阅源

DEV Community