[Feature]: expect.satisfying(fn) — predicate-based asymmetric matcher

[timkindberg]

🚀 Feature Proposal

Add expect.satisfying(fn) as a new built-in asymmetric matcher. Wraps an arbitrary (value) => boolean predicate so it can be used anywhere an asymmetric matcher is accepted: toEqual, toHaveBeenCalledWith, objectContaining, whenCalledWith, etc.

Deferred follow-up from #16053. Listed there as "expect.predicate(fn) - function as asymmetric matcher."

Proposed API

expect.satisfying<T>(fn: (value: T) => boolean): AsymmetricMatcher
expect.not.satisfying<T>(fn: (value: T) => boolean): AsymmetricMatcher

Name chosen for parity with the existing -ing family: objectContaining, stringContaining, stringMatching, arrayContaining. Reads grammatically in assertions ("value satisfying predicate").

Alternatives considered: predicate, check, matching, fn. matching collides with stringMatching. predicate is technically accurate but less natural in prose. fn collides with jest.fn. Happy to swap if maintainers prefer.

Behavior

Match: predicate is invoked with the value. Return is coerced to boolean (truthy = match, falsy = no match). Same coercion semantics as the rest of the asymmetric matcher protocol.

Negation: expect.not.satisfying(fn) flips the boolean. Implemented as a mirrored Not class, same pattern as arrayContaining / objectContaining.

Async throws: Throws at match time with a clear message. Detected via Promise return from the predicate. The asymmetric matcher protocol is sync; silently accepting an async predicate would always pass (a Promise is truthy), which is the worst possible UX.

Errors thrown by predicate: open question, see Pitch section.

toString() output (shows up in failure diffs):

Satisfying[isPositive]       // named function
Satisfying                   // anonymous arrow
Satisfying[positive number]  // with explicit label (if Q1 lands)
NotSatisfying[...]           // negated form

Output format matters for diff readability when multiple satisfying matchers are stacked inside an objectContaining or a whenCalledWith branch list.

TypeScript

T is inferred from the predicate's own parameter, so extracted predicates keep their types:

const isLong = (s: string) => s.length > 0;
expect.satisfying(isLong);                // T = string, inferred
expect.satisfying((n: number) => n > 0);  // T = number, inferred
expect.satisfying(v => !!v);              // T = unknown

Gap: T will not flow in from anyhere
Contextual typing from toHaveBeenCalledWith does not flow into the predicate's parameter, because the matcher position is an AsymmetricMatcher | T union and TS cannot disambiguate to pull the real argument type through to the callback. Known limitation of AsymmetricMatcher being non-generic and structural. Phantom typing (e.g. AsymmetricMatcher & {__matches: T}) could explore this in a future RFC but is invasive and out of scope here.

Motivation

whenCalledWith(...) lets users route mock calls by argument shape. Equality checks plus all existing asymmetric matchers work. What doesn't work today: arbitrary predicates (range checks, cross-field invariants, computed conditions).

// Today: no built-in for predicate-style matching.
// Either fall through and assert on the recorded calls afterwards, or roll a
// custom matcher via expect.extend.
fn.whenCalledWith(/* no way to perform an ad-hoc logic check inline */);

// Wanted:
fn.whenCalledWith(expect.satisfying(req => req.amount > 1000))
  .mockReturnValue('needs-approval');

The same gap exists in toEqual and toHaveBeenCalledWith, but whenCalledWith makes it most painful because branching by ad-hoc predicate is a primary use case for that API.

This is pulling over jest-when's function matchers.

This is sugar, not a new capability. See Pitch for the relationship to expect.extend.

Example

Inline assertion:

expect(user).toEqual({
  age: expect.satisfying(n => n >= 18),
  email: expect.stringMatching(/@/),
});

Composed inside other matchers:

expect(users).toEqual(
  expect.arrayContaining([
    expect.objectContaining({score: expect.satisfying(n => n > 0.5)}),
  ]),
);

Mock argument routing (headline use case):

const charge = jest.fn();

// Threshold split that objectContaining can't express:
charge.whenCalledWith(expect.satisfying(req => req.amount > 1000))
  .mockReturnValue({status: 'needs-approval'});
charge.whenCalledWith(expect.satisfying(req => req.amount <= 1000))
  .mockReturnValue({status: 'auto-approved'});

// Cross-field invariant:
charge.whenCalledWith(expect.satisfying(req => req.start < req.end))
  .mockReturnValue({status: 'ok'});

Negation:

expect(value).toEqual(expect.not.satisfying(isEmpty));

Pitch

Addressing the "matchers belong in jest-extended" note

The form notes that new matchers typically don't make it to core and points at jest-extended. This proposal is different in two ways:

1. It's an asymmetric matcher, not a regular matcher. jest-extended is a collection of assertion-side matchers (expect(x).toBeArrayOfSize(n)). This proposal sits next to any / objectContaining / arrayContaining — the matcher-argument-position primitives. Those are core's job; jest-extended doesn't ship asymmetric matchers in that position.
2. It's a primitive that unlocks whenCalledWith (just merged in feat(jest-mock): add mock.whenCalledWith(...) #16053). Predicate routing was an explicit deferred follow-up. Without it, whenCalledWith ships with a noticeable gap for any mock test that needs to branch on a computed condition rather than a shape match.

So while I understand the "new matchers go to jest-extended" guidance, this one belongs alongside the existing asymmetric matchers in core. Happy to discuss if maintainers disagree.

Relationship to expect.extend

Users can already approximate this today:

expect.extend({
  matchesPredicate(received, fn) {
    return {pass: fn(received), message: () => '...'};
  },
});

// then use anywhere:
expect.matchesPredicate(isPositive);

The asymmetric form of expect.extend matchers does work in toEqual / toHaveBeenCalledWith / whenCalledWith. So this proposal does not add new capability.

What it adds:

1. Standardization. Every codebase that needs this rolls a slightly different version with a different name and format. One built-in fixes that.
2. Discoverability. expect.satisfying shows up next to any / objectContaining in autocomplete and docs. The extend workaround is folklore.
3. Zero setup. No registration, no name to invent, no separate file for expect.extend calls.
4. Consistent failure formatting. A built-in formats toString() the same way every time.

Calling this out explicitly so the "why not just expect.extend" question is preempted.

Open questions

Q1. Optional label argument. Should satisfying(fn, label?) accept an explicit description string used in toString() and failure diffs, or rely solely on fn.name?

• Pro label: anonymous arrows print as Satisfying, which is useless when several are stacked. A label makes diffs readable.
• Con label: no other built-in asymmetric matcher takes a label, so this would be the odd one out.
• Recommendation: support the optional label. Other matchers self-describe from their arguments — StringContaining "foo", Any<String>, the regex literal inside StringMatching. A predicate function body is opaque; there's nothing meaningful to print without help. fn.name covers extracted named predicates but anonymous arrows have empty .name, and arrow source text is too noisy to dump into a diff. satisfying is uniquely opaque among matchers, which is what justifies giving it the only label argument.

Q2. Predicate throw behavior. When the predicate throws, do we propagate the error, or treat it as no-match with a warning?

• Propagate: surfaces buggy predicates loudly. Matches "asymmetric matchers don't run in a try/catch elsewhere" pattern.
• No-match + warn: more forgiving. Risks silent failures masking real bugs.
• Recommendation: propagate.

Implementation plan

Lives entirely in expect. No changes to jest-mock or @jest/expect-utils types. The asymmetric matcher protocol is already in place and whenCalledWith already routes through it after #16053.

Out of scope

• The expect.addEqualityTesters(...) custom-tester gap in whenCalledWith (documented in feat(jest-mock): add mock.whenCalledWith(...) #16053). Different problem. satisfying does not close it.
• The overload-pair type narrowing question from feat(jest-mock): add mock.whenCalledWith(...) #16053. Still deferred.
• E2E tests. None added; matches the precedent set in feat(jest-mock): add mock.whenCalledWith(...) #16053 per maintainer guidance.
• Phantom typing to flow T from outer matcher context into the predicate parameter.

Risks / concerns

• API surface bloat. One additional matcher, low risk. Same shape as the eight existing ones.
• Footgun potential if a user writes a side-effectful predicate. Predicates are user code; not Jest's job to police. Documented as "predicates should be pure."
• Naming bikeshed. Acknowledged. Happy to swap; satisfying is my recommendation but not load-bearing.

References

• feat(jest-mock): add mock.whenCalledWith(...) #16053 — mockFn.whenCalledWith(...) (merged). Original deferred-item listing.
• Issue Parameterised mock return values #6180 — long-running request that feat(jest-mock): add mock.whenCalledWith(...) #16053 closed; predicate matching mentioned in the thread.

[timkindberg]

@SimenB and @jeysal this is the RFC for expect.satisfying that Simen said he was interested in. Please review and let me know your appetite for this as a follow up.

[ahnpnl]

I guess we can have same matcher like this https://vitest.dev/api/expect.html#tosatisfy

[jeysal]

Pro label: anonymous arrows print as Satisfying, which is useless when several are stacked. A label makes diffs readable.

I agree, but I think we should put in a safeguard for the worst case.
If someone passes a
const x = () => { /* huge body */ }; expect.satisfying(x); we should cut it off like diffs, or more aggressively perhaps.

[jeysal]

I agree with all other decisions in the RFC, if we do go down this route.
One other idea to throw in: We could force naming the predicate expect.satisfying("is big number", n => n > 42).

[jeysal]

I would like to discuss the approach a bit more generally though.

I'm seeing a few gaps in matchers:

1. charge.whenCalledWith(expect.satisfying(req => req.amount > 1000)) - this can just be solved with expect.greaterThan etc.
2. cross-field
3. some of these could be solved with e.g. an or() over the object matchers like or(objectMatching({ amount: gt(1000), mode: 'credit' }), objectMatching({ amount: gt(1000) }) (as long as each matcher is independent of one another)
4. not the req.start < req.end example indeed. But I'm wondering just how often these cases will appear for it to be worth it, esp. given there's always a way to opt out with both assertions and mocks and process parameters yourself instead

I'm not sure if I'm convinced that these gaps are big enough, esp. if we introduce additional matchers where people really need it badly, to justify providing an extremely powerful satisfying matcher for the few remainings cases that we can't provide a good experience out of the box for because we don't have a way to statically analyze it and generate nice diffs for it.

[timkindberg]

We could force naming the predicate expect.satisfying("is big number", n => n > 42)

That is actually what the "label" idea was about, it wasn't about capturing the body of the function it was about allowing devs to provide a string to give it a better human-readable label. If not provided it would fallback to the function's .name if available.

I'm seeing a few gaps in matchers:

It's true I am not sure what usage patterns are and what actual demand for this really is. All I know is jest-when had it and it seems like a flexible enough primitive. So jest prefers providing higher-level abstractions over lower-level abstractions? In jest-when I was just like "here this should be enough for whatever anyone wants to do" as a way to not have to maintain so many one-off things, but it sounds like you might prefer providing lots of one-off things for ppl instead of one more generic thing.

We could always just wait and see what ppl complain about!

[jeysal]

I wouldn't say 'prefer providing higher-level over lower-level' as a general principle. Just that it seems here we could either cover 100% of the use cases with a subpar experience or 80% with a good one.
And yeah indeed we don't really know the number 80%, or even how big the 100% slice of users is.
Also ofc curious how @SimenB thinks about this.