Feature: matcher for standard schema

[zirkelc]

Clear and concise description of the problem

I created the custom matcher expect-match-schema for schema validation based on a Standard Schema like Zod, Valibot, ArkType, etc.

test('should pass for valid data', () => {
  const schema = z.object({
    name: z.string(),
    email: z.email(),
  });

  const validData = { name: 'John', email: 'john@example.com' };
  expect(validData).toMatchSchema(schema);
});

Since Standard Schema just specifies an interface without depending on the actual schema libraries like Zod, the implementation is quite lightweight.

It has received good feedback on Twitter and I thought this might be a good feature to be natively supported by Vitest: https://x.com/zirkelc_/status/1958534349319553418

Suggested solution

See PR #8527

Three options have been implemented for further discussion:

• custom equality tester for expect.toEqual()
• custom matcher expect.toEqualSchema()
• asymmetric matcher expect.schemaMatching()

const schema = z.object({
  name: z.string(),
  email: z.email(),
});
const validData = { name: 'John', email: 'john@example.com' };

// custom equality test using toEqual
expect(validData).toEqual(schema);
expect({ email: "john@example.com" }).toEqual({ email: z.email() });

// custom matcher using toEqualSchema
expect(validData).toEqualSchema(schema);
expect({ email: "john@example.com" }).toEqualSchema({ email: z.email() });

// asymmetric matcher
expect(validData).toEqual(expect.schemaMatching(schema));
expect({ email: "john@example.com" }).toEqual(expect.schemaMatching({ email: z.email() }));

Alternative

No response

Additional context

If approved, I'd like to submit a PR for this feature.

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[sheremet-va]

There was already a discussion about Standard Schema at #7015 (comment)

I am open to discuss how it can be integrated into Vitest if someone creates a thread with an API proposal, and how it integrates with existing APIs (with a comparison to expect.any* and other matchers). Having only toHaveSchema doesn't seem enough to justify adding it.

[zirkelc]

@sheremet-va thanks for referencing the comment.

I will prepare an API proposal with examples and comparisons.

Should this discussion take place here or in a separate discussion thread?

[hi-ogawa]

You can continue on this issue. So far, the team has discussed that we can explore supporting standard schema directly as asymmetric matcher i.e. you can use it on the right side of current toEqual API etc. For example:

const schema = z.object({
  name: z.string(),
  email: z.email(),
});
const validData = { name: 'John', email: 'john@example.com' };
expect(validData).toEqual(schema);
expect({ email: "john@example.com" }).toEqual({ email: z.email() });

API proposal is fine too, but also it's very welcome if some tries proof of concept of implementing this. It may be already possible on user land with custom expect.addEqualityTesters https://vitest.dev/api/expect.html#expect-addequalitytesters

[zirkelc]

Thanks, I will prepare a PR for further discussion!

[zirkelc]

@hi-ogawa I implemented a PoC in #8527

[dominikg]

I'd prefer this to use toMatchSchema or similar.

toEqual reads wrong unless the left hand side would be a schema as well and not a value to be matched with the schema.

its basically equivalent to expect("foo").toEqual(/foo/) which should fail because one is a regex and the other is a string

[sheremet-va]

I'd prefer this to use toMatchSchema or similar.

toEqual reads wrong unless the left hand side would be a schema as well and not a value to be matched with the schema.

its basically equivalent to expect("foo").toEqual(/foo/) which should fail because one is a regex and the other is a string

Your example could also be written like this: expect("foo").toEqual(expect.stringContaining(/foo/)) which already works. The reason why toEqual works is because asymetric matchers can be used anywhere where equality is checked. For example, when validating spy calls:

expect(spy).toHaveBeenCalledWith({
+  email: v.email(),
-  email: expect.stringMatching(emailRegexp())
})

toEqual is not the only example of this. Having a single toMatchSchema would be very limiting.

[lukeed]

It should be toMatch() or satisfies(). It does not equal the schema itself.