feat(expect): add toBeOneOf matcher

[zirkelc]

Description

Following the discussion #6961 I'd suggest to add a new asymmetric matcher expect.oneOf() for better support of optional properties, which can often be undefined or null if not set.

test('optional properties can be null or undefined', () => {
  const user = {
    id: 1,
    firstName: 'John',
    middleName: undefined,
    lastName: 'Doe'
  }

  expect(user).toEqual({
    id: expect.any(Number),
    firstName: expect.any(String),
    middleName: expect.oneOf([expect.any(String), undefined]),
    lastName: expect.any(String),
  })
})

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
• Ideally, include a test that fails without this PR but passes with it.
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

[netlify]

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	6f21c89
🔍 Latest deploy log	https://app.netlify.com/sites/vitest-dev/deploys/67651ffefc62ea00084ee677
😎 Deploy Preview	https://deploy-preview-6974--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[hi-ogawa]

We still need to discuss if this is actually worth it in builtin, but thanks for kicking it off!

One thing I wasn't sure is how error diff works. Can you add a test cases for that? You can find examples at the bottom of jest-expect.test.ts using snapshotError.

[zirkelc]

@hi-ogawa I added the snapshot tests

[hi-ogawa]

I just found jest-extended provides toBeOneOf https://jest-extended.jestcommunity.dev/docs/matchers/toBeOneOf
Their example is only the assertion version, but they supports asymmetric version too. Maybe should we just align with this? 🤔

[zirkelc]

That's a good idea. Just to be clear, you mean adding expect().toBeOneOf([]) additionally to the asymmetric expect.oneOf([])?

[sheremet-va]

That's a good idea. Just to be clear, you mean adding expect().toBeOneOf([]) additionally to the asymmetric expect.oneOf([])?

Kind of. If you use expect.extend, then it will be added to both automatically, so just do it that way 😄

[hi-ogawa]

I added a example of adding toSatisfy internally via expect.extend in #7022
Can you make it something similar for toBeOneOf? 🙏

[zirkelc]

I changed it to a custom matcher. Let me know if anything else should be changed.

[zirkelc]

The diff doesn't handle null and undefined correctly. It should be:

Suggested change

	toBeOneOf<Any,,>
	toBeOneOf<Any,null,undefined>

[hi-ogawa]

Hmm, this is unfortunate. Maybe can we try stringify instead of String? 🤔

vitest/packages/expect/src/jest-extend.ts

Lines 134 to 136 in 021944c

	toAsymmetricMatcher() {
	return `${this.toString()}<${this.sample.map(String).join(', ')}>`
	}

[zirkelc]

Yes, this is better. But it also affects toSatisfy()

[zirkelc]

It prints the function name instead of its implementation

[hi-ogawa]

This is alright since this is how we normally format the function, so I guess we can say it's a better alignment.

[zirkelc]

Not sure about this

[hi-ogawa]

Yeah, this looks puzzling, but what's happening is we have truncation logic here for main error message and that just kicked in due to toSatisfy format got a bit longer. This is fine as well.

[hi-ogawa]

Looks good to me!

[hi-ogawa]

This is alright since this is how we normally format the function, so I guess we can say it's a better alignment.

[hi-ogawa]

Yeah, this looks puzzling, but what's happening is we have truncation logic here for main error message and that just kicked in due to toSatisfy format got a bit longer. This is fine as well.