expect.toMatchSchema()

This package provides a custom matcher for Vitest and Jest to check data against a standard schema like Zod, ArkType, Valibot and others.

Standard Schema

Standard Schema is a common interface designed to be implemented by JavaScript and TypeScript schema libraries. The goal is to make it easier for ecosystem tools to accept user-defined type validators, without needing to write custom logic or adapters for each supported library. And since Standard Schema is a specification, they can do so with no additional runtime dependencies. Integrate once, validate anywhere.

Install

Install expect-match-schema as a dev dependency:

pnpm add -D expect-match-schema

Usage

Import toMatchSchema and use expect.extend to extend the default matchers.

import { describe, expect, test } from 'vitest';
import { toMatchSchema } from 'expect-match-schema';
import { z } from 'zod';
import { type } from 'arktype';
import * as v from 'valibot';

expect.extend({ toMatchSchema });

const data = { email: '[email protected]' };

test("should validate using Zod", () => {
  expect(data).toMatchSchema(
    z.object({
      email: z.email(),
    }),
  );
});

test("should validate using Valibot", () => {
  expect(data).toMatchSchema(
    v.object({
      email: v.pipe(v.string(), v.email()),
    }),
  );
});

test("should validate using ArkType", () => {
  expect(data).toMatchSchema(
    type({
      email: 'string.email',
    }),
  );
});

Asymmetric Matchers

You can also use expect.toMatchSchema() as an asymmetric matcher with expect.objectContaining, expect.arrayContaining, and similar matchers:

test('should validate using Zod', () => {
  const response = {
    user: {
      name: 'John Doe',
      email: '[email protected]',
      id: 123,
    },
    timestamp: new Date().toISOString(),
  };

  expect(response).toEqual({
    user: expect.objectContaining({
      name: expect.toMatchSchema(z.string()),
      email: expect.toMatchSchema(z.email()),
    }),
    timestamp: expect.toMatchSchema(z.iso.datetime()),
  });
});

API

toMatchSchema(schema: StandardSchemaV1)

Accepts any schema that implements the Standard Schema specification. The matcher expects a synchronous schema and will throw an error if the schema is asynchronous.

License

MIT