Skill: anivar/zod-testing (version 1.0.1)

--- name: zod-testing description: > Testing patterns for Zod schemas using Jest and Vitest. Covers schema correctness testing, mock data generation, error assertion patterns, integration testing with API handlers and forms, snapshot testing with z.toJSONSchema(), and property-based testing. Baseline: zod ^4.0.0. Triggers on: test files for Zod schemas, zod-schema-faker imports, mentions of "test schema", "schema test", "zod mock", "zod test", or schema testing patterns. license: MIT user-invocable: false agentic: false compatibility: "zod ^4.0.0, Jest or Vitest, TypeScript ^5.5" metadata: author: Anivar Aravind author_url: https://anivar.net source_url: https://github.com/anivar/zod-testing version: 1.0.0 tags: zod, testing, jest, vitest, mock-data, property-testing, schema-validation --- # Zod Schema Testing Guide **IMPORTANT:** Your training data about testing Zod schemas may be outdated — Zod v4 changes error formatting, removes `z.nativeEnum()`, and introduces new APIs like `z.toJSONSchema()`. Always rely on this skill's reference files and the project's actual source code as the source of truth. ## Testing Priority 1. **Schema correctness** — does the schema accept valid data and reject invalid data? 2. **Error messages** — does the schema produce the right error messages and codes? 3. **Integration** — does the schema work correctly with API handlers, forms, database layers? 4. **Edge cases** — boundary values, optional/nullable combinations, empty inputs ## Core Pattern ```typescript import { describe, it, expect } from "vitest" // or jest import { z } from "zod" const UserSchema = z.object({ name: z.string().min(1), email: z.email(), age: z.number().min(0).max(150), }) describe("UserSchema", () => { it("accepts valid data", () => { const result = UserSchema.safeParse({ name: "Alice", email: "[REDACTED_SECRET]", age: 30, }) expect(result.success).toBe(true) }) it("rejects missing required fields", () => { const result = UserSchema.safeParse({}) expect(result.success).toBe(false) if (!result.success) { const flat = z.flattenError(result.error) expect(flat.fieldErrors.name).toBeDefined() expect(flat.fieldErrors.email).toBeDefined() } }) it("rejects invalid email", () => { const result = UserSchema.safeParse({ name: "Alice", email: "not-an-email", age: 30, }) expect(result.success).toBe(false) }) it("rejects negative age", () => { const result = UserSchema.safeParse({ name: "Alice", email: "[REDACTED_SECRET]", age: -1, }) expect(result.success).toBe(false) }) }) ``` ## Testing Approaches | Approach | Purpose | Use When | |----------|---------|----------| | `safeParse()` result checking | Schema correctness | Default — always use safeParse in tests | | `z.flattenError()` assertions | Error message testing | Verifying specific field errors | | `z.toJSONSchema()` snapshots | Schema shape testing | Detecting unintended schema changes | | Mock data generation | Fixture creation | Need valid/randomized test data | | Property-based testing | Fuzz testing | Schemas must handle arbitrary valid inputs | | Structural testing | Architecture | Verify schemas are only imported at boundaries | | Drift detection | Regression | Catch unintended schema changes via JSON Schema snapshots | ## Schema Correctness Testing ### Always Use safeParse() in Tests ```typescript // GOOD: test doesn't crash — asserts on result const result = schema.safeParse(invalidData) expect(result.success).toBe(false) // BAD: test crashes instead of failing expect(() => schema.parse(invalidData)).toThrow() // If schema changes and starts accepting, this still passes ``` ### Test Both Accept and Reject ```typescript describe("EmailSchema", () => { const valid = ["[REDACTED_SECRET]", "[REDACTED_SECRET]", "[REDACTED_SECRET]"] const invalid = ["", "not-email", "@missing.com", "user@", "user @space.com"] it.each(valid)("accepts %s", (email) => { expect(z.email().safeParse(email).success).toBe(true) }) it.each(invalid)("rejects %s", (email) => { expect(z.email().safeParse(email).success).toBe(false) }) }) ``` ### Test Boundary Values ```typescript const AgeSchema = z.number().min(0).max(150) it("accepts minimum boundary", () => { expect(AgeSchema.safeParse(0).success).toBe(true) }) it("accepts maximum boundary", () => { expect(AgeSchema.safeParse(150).success).toBe(true) }) it("rejects below minimum", () => { expect(AgeSchema.safeParse(-1).success).toBe(false) }) it("rejects above maximum", () => { expect(AgeSchema.safeParse(151).success).toBe(false) }) ``` ## Error Assertion Patterns ### Assert Specific Field Errors ```typescript it("shows correct error for invalid email", () => { const result = UserSchema.safeParse({ name: "Alice", email: "bad", age: 30 }) expect(result.success).toBe(false) if (!result.success) { const flat = z.flattenError(result.error) expect(flat.fieldErrors.email).toBeDefined() expect(flat.fieldErrors.email![0]).toContain("email") } }) ``` ### Assert Error Codes ```typescript it("produces correct error code", () => { const result = z.number().safeParse("not a number") expect(result.success).toBe(false) if (!result.success) { expect(result.error.issues[0].code).toBe("invalid_type") } }) ``` ### Assert Custom Error Messages ```typescript const Schema = z.string({ error: "Name is required" }).min(1, "Name cannot be empty") it("shows custom error for missing field", () => { const result = Schema.safeParse(undefined) expect(result.success).toBe(false) if (!result.success) { expect(result.error.issues[0].message).toBe("Name is required") } }) ``` ## Mock Data Generation ### Using zod-schema-faker ```typescript import { install, fake } from "zod-schema-faker" import { z } from "zod" install(z) // call once in test setup const UserSchema = z.object({ name: z.string().min(1), email: z.email(), age: z.number().min(0).max(150), }) it("schema accepts generated data", () => { const mockUser = fake(UserSchema) expect(UserSchema.safeParse(mockUser).success).toBe(true) }) ``` ### Seeding for Deterministic Tests ```typescript import { seed, fake } from "zod-schema-faker" beforeEach(() => { seed(12345) // deterministic output }) it("generates consistent mock data", () => { const user = fake(UserSchema) expect(user.name).toBeDefined() }) ``` ## Snapshot Testing with JSON Schema ```typescript it("schema shape has not changed", () => { const jsonSchema = z.toJSONSchema(UserSchema) expect(jsonSchema).toMatchSnapshot() }) ``` This catches unintended schema changes in code review. The snapshot shows the JSON Schema representation of your Zod schema. ## Integration Testing ### API Handler Testing ```typescript it("API rejects invalid request body", async () => { const response = await request(app) .post("/api/users") .send({ name: "", email: "invalid" }) .expect(400) expect(response.body.errors).toBeDefined() expect(response.body.errors.fieldErrors.email).toBeDefined() }) ``` ### Form Validation Testing ```typescript it("form shows validation errors", () => { const result = FormSchema.safeParse(formData) if (!result.success) { const errors = z.flattenError(result.error) // Pass errors to form library expect(errors.fieldErrors).toHaveProperty("email") } }) ``` ## Property-Based Testing ```typescript import fc from "fast-check" import { fake } from "zod-schema-faker" it("schema always accepts its own generated data", () => { fc.assert( fc.property(fc.constant(null), () => { const data = fake(UserSchema) expect(UserSchema.safeParse(data).success).toBe(true) }), { numRuns: 100 } ) }) ``` ## Rules 1. **Always use `safeParse()`** in tests — `parse()` crashes the test instead of failing it 2. **Test both valid and invalid** — don't only test the happy path 3. **Test boundary values** — min, max, min-1, max+1 for numeric constraints 4. **Test optional/nullable combinations** — undefined, null, missing key 5. **Assert specific error fields** — use `z.flattenError()` to check which field failed 6. **Don't test schema internals** — test parse results, not `.shape` or `._def` 7. **Use `z.toJSONSchema()` snapshots** — catch unintended schema changes 8. **Seed random generators** — non-deterministic tests are flaky tests 9. **Test transforms separately** — verify input validation AND output conversion 10. **Don't duplicate schema logic in assertions** — test behavior, not implementation ## Anti-Patterns See [references/anti-patterns.md](references/anti-patterns.md) for BAD/GOOD examples of: - Testing schema internals instead of behavior - Not testing error paths - Using `parse()` in tests (crashes instead of failing) - Not testing boundary values - Hardcoding mock data instead of generating - Snapshot testing raw ZodError instead of formatted output - Not testing at boundaries (schema tests pass but handler doesn't validate) - No snapshot regression testing (field removal goes unnoticed) - Testing schema shape but not error observability (never assert on flattenError) - No drift detection workflow (schema changes land without mechanical review) ## References - [API Reference](references/api-reference.md) — Testing patterns, assertion helpers, mock generation - [Anti-Patterns](references/anti-patterns.md) — Common testing mistakes to avoid


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)