Skip to content

bun:test: give the built-in and expect.extend() matchers one asymmetricMatch() - #48640

Draft
robobun wants to merge 2 commits into
robobun/ec4561b1/print-array-containing-samplefrom
robobun/32930ee0/builtin-asymmetric-match
Draft

robobun wants to merge 2 commits into
robobun/ec4561b1/print-array-containing-samplefrom
robobun/32930ee0/builtin-asymmetric-match

Conversation

@robobun

@robobun robobun commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #47996. Draft until it merges.

Problem

  • expect.any() and the six other built-in matchers have no asymmetricMatch(), so your own matcher cannot ask one: TypeError: expect.any(Number).asymmetricMatch is not a function.
  • equals(1, expect.any(Number)) of @jest/expect-utils is false: it looks for that method. No user reported this.
  • Cause: their classes declare no prototype members (src/runtime/test_runner/expect.bind.ts:17).

Fix

  • One schema const gives all eight matcher classes the method, not enumerable, as in Jest.
  • One Rust body runs received.jest_deep_equals(matcher), the call of toEqual(): 342 of 342 probed cells agree. A resolvesTo or rejectsTo matcher throws for a pending promise.
  • Verified: test/js/bun/test/expect.test.js (18 tests, 16 fail without the fix). Also expect-extend, jest-extended, mock-fn, inspect, bun-types.
  • Self-reviewed: 12 concerns raised, 12 addressed. Not taken: JSDoc on each factory (the AsymmetricMatcher type has it).

Background

  • An asymmetric matcher stands in for a value inside toEqual(). Jest and Vitest ask it through matcher.asymmetricMatch(value).
  • The eighth class serves expect.extend(). Its method did not read a promise first.
  • Without the printer arm of bun:test: print expect.arrayContaining() with its sample #47996, Bun.inspect(expect.arrayContaining([1])) lists the new method.
  • Considered an entry in bindings.cpp (same verdicts, 51 more lines of C++) and a base class (expect.anything() grows by 16 bytes).

Downsides

  • expect.extend() matchers from expect.resolvesTo or expect.rejectsTo: the method changes in 12 of 42 cells. for...in no longer lists it.
  • Release binary: .text +1,120 B, .rodata +4,352 B (size -A, --lto=off). Per global: +1 function per class.
  • toEqual() with a matcher: 1,727 instructions before, 1,725 after. expect.toSatisfy(fn).asymmetricMatch(1): 3,924 to 3,927, run spread 12.
Notes

What changes for existing tests

  • expect.extend() and expect.toSatisfy() matchers made through expect.resolvesTo / expect.rejectsTo (also behind expect.not): asymmetricMatch() now unwraps a settled promise, answers false for a value that is not a promise, and throws An async matcher only works inside an expect() matcher, which then returns a promise: await expect(received).toEqual(expected) for a pending promise. Before, the matcher function got the promise itself. 12 of 42 cells change per matcher (6 chains by 7 values): 8 answers flip and 4 pending promises throw. Without a promise flag 0 of 14 cells change. Example: expect.resolvesTo.toBeOdd().asymmetricMatch(Promise.resolve(1)) was false and is true.
  • Such a matcher marks the promise that it reads as handled, as toEqual() does.
  • ExpectCustomAsymmetricMatcher.prototype.asymmetricMatch has shipped since 1.0.15 as enumerable and not configurable. It is now not enumerable and configurable.
  • With a this that is no matcher of its class the method answers undefined. The expect.extend() one threw Expected this to be instanceof ExpectCustomAsymmetricMatcher. printDiffOrStringify of jest-matcher-utils 30.5.2 calls the method on such a copy: of 20 probed cases 2 throw on main and 0 throw here.
  • A copy of a built-in matcher that keeps its prototype (Object.create(Object.getPrototypeOf(matcher))), and the prototype itself, now have the method. toEqual() takes such an object for a matcher that matches nothing, and Bun.inspect() lists asymmetricMatch on the copy. On main it compares as an empty object and prints as ExpectAny {}.
  • No text that Bun.inspect() prints for a matcher changes: 36 rows are the same with and without this PR (9 matchers from expect, expect.not, expect.resolvesTo and expect.rejectsTo, each plain, nested and with showHidden).

The contract

  • matcher.asymmetricMatch(value) compares as toEqual() does. It is not the answer of Jest in every cell, because bun's toEqual() already differs from the method of Jest 30.5.2 in some. Four examples, bun then Jest: expect.arrayContaining([]) on "x" (false, true), expect.closeTo(1) on new Number(1) (false, true), expect.stringContaining("a") on new String("a") (false, true), expect.not.objectContaining({ a: 1 }) on 1 (true, false). The method inherits these.
  • toEqual() still asks a matcher of expect by its class. It does not call a function that a test stored over the method: after matcher.asymmetricMatch = () => true on an expect.any(Number), expect("x").toEqual(matcher) still fails.
  • A direct call reads the equality testers of expect.addEqualityTesters(), also under import ... from "vitest". Vitest 5.1.0 reads only its second argument there. The method takes one argument (length 1, Vitest has 2 for arrayContaining and objectContaining).
  • Not added: $$typeof, sample, inverse, toString(), toAsymmetricMatcher(), getExpectedType(). A library that prints with its own printer still sees a plain object.
  • jest-diff diff(expect.any(Number), 1) returns null where it returned Comparing two different types of values. diff of @vitest/utils returns undefined where it returned - Expected: {} / + Received: 1.
  • calledWith(expect.any(Number)) of vitest-mock-extended 6.0.0 and of vitest-when 1.0.0 now matches. calledWith() of jest-mock-extended 4.0.2 still matches nothing: it also needs the jest.fn(undefined) fix of bun test: follow-ups to Vitest compatibility #47727. jest-when 4.0.3 does not load with or without this PR.
  • A ninth matcher class gets the method only if its schema spreads the const. The test "every function of expect.not makes a matcher that has the method" fails for a class that does not.

Measurements

Release builds with --lto=off of main 89452d2 with #47996 (before), and of the same tree with this PR (after). linux x64.

  • Sections (size -A): .text +1,120 B, .rodata +4,352 B, .eh_frame +80 B. The stripped file grows by 4,096 B.
  • Symbols (nm -S): to_equal_verdict 1 copy, 177 B. 7 new Rust thunks of 56 B. 8 host functions of 70 B, 7 of them new (the one of the expect.extend() class was 79 B). 7 new prototype tables of 40 B. The Rust thunk of the expect.extend() class: 176 B to 201 B.
  • Generated host functions in GeneratedExpect.cpp: 154 to 161. asymmetricMatch entries in the table of built-ins of the ahead-of-time compiler: 1 to 8 (7,240 to 7,247 entries).
  • Instructions per iteration (perf_event_open instructions:u, BUN_JSC_useJIT=0, (I(2N) - I(N)) / N), before and after:
    • expect(1).toEqual(matcher) with expect.any(Number) made once: 1,727 and 1,725.
    • expect(1).toEqual(expect.any(Number)): 2,284 and 2,278.
    • expect({ a: [1, 2] }).toEqual({ a: matcher }) with expect.arrayContaining() made once: 3,019 and 3,017.
    • expect.any(Number): 683 and 683.
    • expect.toSatisfy(fn).asymmetricMatch(1): 3,924 and 3,927. 7 runs of one binary spread over 12.
    • expect.any(Number).asymmetricMatch(1): 484 after (600 with the loop, 116 for the empty loop).
    • Bun.inspect(new net.SocketAddress(..)): 21,525 and 21,525.
  • src/jsc/bindings/bindings.cpp: 0 lines changed. toEqual() runs the code that it ran.
  • Startup, bun -e 0, 10 runs: 4,433,796 to 4,470,090 instructions before, 4,435,966 to 4,454,050 after.
  • System calls of bun test on one file with six matchers (counted with ptrace): 279 to 280 before, 277 to 286 after.
  • GC cells (heapStats().objectTypeCounts): +0 per matcher object. Per global, on the first object of a class: +1 Function and +1 NativeExecutable. Per call of a built-in method: 0. expect.resolvesTo.any(Number).asymmetricMatch(1): 1 Promise per call. The method of the expect.extend() class: 2 cells per call before and after.
  • Method against toEqual(): 0 of 342 cells differ (9 matchers by 6 chains by 7 values, without the 36 cells where toEqual() waits and the method throws).
  • bloaty, valgrind, perf and strace are not installed here. The two counters are small C programs over perf_event_open and ptrace.
  • Executables of bun build --compile --aot, as test/bundler/compile-aot-size.test.ts prints them in CI (LTO, linux x64), for the base branch and then for this PR: the compiler takes 23,663,539 and 23,663,789 bytes. hello world maps 68,117,555 and 68,117,683 bytes. hello world --trim maps 25,986,099 and 25,973,939 bytes. The bound of that test for --trim is 25,880,000 bytes, so it fails on the base branch and here.

Tests

  • expect.test.js, 18 tests: the answers of 17 matchers against values that match and values that do not, each also through toEqual(). The descriptor. A matcher of your own that hands the value on, allOf and anyOf. Code that looks for the method. Matchers inside a sample. No assertion counted. Errors thrown while it matches. Another this. 252 cells of 7 matchers from 6 chains against toEqual(), and 72 cells for expect.extend() and expect.toSatisfy(). Pending promises. A child process with an equality tester and with rejections that nothing else handles. What Bun.inspect() prints. Every function of expect.not.
  • The first 8 are written for any runner. They pass on Jest 30.5.2 and Vitest 5.1.0.
  • test/integration/bun-types/fixture/test.ts type-checks the docs example.
  • Also ran on a debug build of this branch: expect-extend, expect-extend-asymmetric-match-throw, expect-extend-matcher-utils-throw, expect-extend-preload, jest-extended, mock-fn, spyMatchers, expect-label, expect-toHaveReturnedWith, pretty-format-overflow, pretty-format-overridden-size, expect-stack-overflow-crash, expect-assertions, 12650, inspect.test.js, and from test/aot/builtins: differential/operands, differential/wrong-columns, own-properties, module-exports, proven-returns, name-classes, classes-with-inspect-method.
  • On a release build of this branch (--lto=off): test/aot/builtins/differential.test.ts passes (6,567 tests, the 8 asymmetricMatch entries among them), and so do native-contract.test.ts for the Expect entries and expect.test.js. On main with bun:test: print expect.arrayContaining() with its sample #47996 and this PR, differential.test.ts passes too (6,953 tests).

Open PRs on the same lines

…method

The objects that expect.any(), expect.anything(), expect.arrayContaining(),
expect.closeTo(), expect.objectContaining(), expect.stringContaining() and
expect.stringMatching() return had no asymmetricMatch(). A matcher of your
own could not ask them, and code that tells a matcher by that method, such
as equals() of @jest/expect-utils, took them for plain values.

One schema const gives the seven classes the method, through the trait
AsymmetricMatcher. It returns what deep equality decides for the matcher as
the expected value, which is what toEqual() runs. The answer goes to the
caller at once, so a matcher of expect.resolvesTo or expect.rejectsTo reads
a settled promise and throws for a pending one.

As in Jest and Vitest the method is not enumerable and is configurable.
A copy of a matcher that keeps its prototype, as jest-matcher-utils makes
one before it prints a diff, is no matcher: there the method answers
undefined and does not throw.
…e toEqual()

A matcher of expect.extend() or expect.toSatisfy() had the method already.
It handed the value to the matcher function as it was, so for a matcher
from expect.resolvesTo or expect.rejectsTo it disagreed with toEqual(),
which reads the promise first: a settled promise was not unwrapped, a value
that is no promise could match, and a pending promise got an answer.

The class now takes the method of the built-in matchers. With a promise
flag it returns what deep equality decides and throws for a pending
promise. Without one it calls the matcher function as before. The method
is no longer enumerable, is configurable, and answers undefined for a
`this` that is no matcher.
@robobun

robobun commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status: draft, stacked on #47996.

How to reproduce the problem on main:

import { expect } from "bun:test";

console.log(typeof expect.any(Number).asymmetricMatch); // "undefined". Jest 30.5.2 and Vitest 5.1.0 print "function".
expect.any(Number).asymmetricMatch(1); // TypeError: expect.any(Number).asymmetricMatch is not a function

Without the change to src/, 16 of the 18 new tests in test/js/bun/test/expect.test.js fail. With it, the file passes.

CI: test/js/bun/test/expect.test.js passes on every lane of build 140326 (483 tests). The red tests are not tests of this change:

  • The tests under test/aot/ and the --trim bound of test/bundler/compile-aot-size.test.ts are also red in build 137920 of the base branch (bun:test: print expect.arrayContaining() with its sample #47996), which does not have this diff. The base branch starts at main of 2026-11-05 (b1305dd).
  • One ASAN job ran out of time while it retried test/aot/three-layers-agree.test.ts, where an --aot test run ends with exit code 134. Build 137920 has the same failure of that test on the same lane.
  • test/js/web/request/request-clone-leak.test.ts on the ASAN lane measured an RSS delta of 64 MB against a bound of 64 MB. Main has since changed how that test measures memory.

@robobun

robobun commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 7:06 PM PT - Nov 11th, 2026

❌ @robobun, your commit 534bf17 has 39 failures in Build #140326 (All Failures):


🧪   To try this PR locally:

bunx bun-pr 48640

That installs a local version of the PR into your bun-48640 executable, so you can run:

bun-48640 --bun

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant