test: allow onTestFinished() and expect.assertions() in concurrent tests

docs/test/lifecycle.mdx

@@ -106,7 +106,7 @@ test("cleanup after test", () => {
 });
 ```
 
-Not supported in concurrent tests; use `test.serial` instead.
+Works inside concurrent tests when `onTestFinished()` is called synchronously from the test callback body (including microtasks drained before the first suspension point). Registrations made after yielding to a later event-loop turn — for example after `await`ing a timer — may not resolve which concurrent sequence they belong to.
 
 ## Global Setup and Teardown
 

packages/bun-types/test.d.ts

@@ -380,6 +380,12 @@ declare module "bun:test" {
    *
    * Can only be called inside a test, not in describe blocks.
    *
+   * Works inside concurrent tests when `onTestFinished()` is called
+   * synchronously from the test callback body (including microtasks drained
+   * before the first suspension point). Registrations made after yielding to
+   * a later event-loop turn — for example after `await`ing a timer — may
+   * not resolve which concurrent sequence they belong to.
+   *
    * @example
    * test("my test", () => {
    *   onTestFinished(() => {
@@ -705,12 +711,24 @@ declare module "bun:test" {
     unreachable(msg?: string | Error): never;
 
     /**
-     * Ensures that an assertion is made
+     * Ensures that an assertion is made.
+     *
+     * Not supported in concurrent tests — use `test.serial` or remove
+     * `.concurrent` from the enclosing test. Unlike `onTestFinished()`,
+     * this cannot be resolved to the owning sequence across `await`
+     * boundaries, so it throws unconditionally rather than silently
+     * miscounting.
      */
     hasAssertions(): void;
 
     /**
-     * Ensures that a specific number of assertions are made
+     * Ensures that a specific number of assertions are made.
+     *
+     * Not supported in concurrent tests — use `test.serial` or remove
+     * `.concurrent` from the enclosing test. Unlike `onTestFinished()`,
+     * this cannot be resolved to the owning sequence across `await`
+     * boundaries, so it throws unconditionally rather than silently
+     * miscounting.
      */
     assertions(neededAssertions: number): void;
   }

src/bun.js/test/Execution.zig

@@ -397,6 +397,21 @@ fn stepSequenceOne(buntest_strong: bun_test.BunTestPtr, globalThis: *jsc.JSGloba
         };
         groupLog.log("runSequence queued callback: {f}", .{callback_data});
 
+        // Mark this sequence/entry as the synchronously-executing callback
+        // so that `onTestFinished()` can look up which concurrent sequence
+        // it belongs to. Any awaited microtasks that are drained by
+        // `runCallbackWithResultAndForcefullyDrainMicrotasks` also see this
+        // context. The context is popped once the JS call returns, even if
+        // the returned promise is still pending.
+        //
+        // `expect.assertions()` / `expect.hasAssertions()` / snapshot
+        // matchers deliberately do NOT use this stack — they reject
+        // upfront in multi-sequence concurrent groups (see `expect.zig`)
+        // because their subsequent `expect(v)` matchers can't resolve the
+        // owning sequence once control has returned to the event loop.
+        buntest.pushCurrentCallback(callback_data);
+        defer buntest.popCurrentCallback();
+
         if (BunTest.runTestCallback(buntest_strong, globalThis, cb.get(), next_item.has_done_parameter, callback_data, &next_item.timespec) != null) {
             now.* = bun.timespec.now(.force_real_time);
             _ = next_item.evaluateTimeout(sequence, now);

src/bun.js/test/bun_test.zig

@@ -77,10 +77,18 @@ pub const js_fns = struct {
                     .execution => {
                         const active = bunTest.getCurrentStateData();
                         const sequence, _ = bunTest.execution.getCurrentAndValidExecutionSequence(active) orelse {
+                            // We only reach this branch when `current_callback_stack` is
+                            // empty *and* the active concurrent group has more than one
+                            // sequence in flight. The common way to hit this is calling
+                            // the hook after the first `await` in a concurrent test —
+                            // by then the synchronous push/pop has already been popped
+                            // and we can no longer tell which sequence the caller
+                            // belongs to. Tell the user to hoist the call above the
+                            // first `await`, which is the only actionable fix here.
                             const message = if (tag == .onTestFinished)
-                                "Cannot call {s}() here. It cannot be called inside a concurrent test. Use test.serial or remove test.concurrent."
+                                "Cannot call {s}() here. In a concurrent test, call it synchronously before the first `await`."
                             else
-                                "Cannot call {s}() here. It cannot be called inside a concurrent test. Call it inside describe() instead.";
+                                "Cannot call {s}() here. In a concurrent test, call it synchronously before the first `await`, or move it into a describe() block.";
                             return globalThis.throw(message, .{@tagName(tag)});
                         };
 
@@ -219,6 +227,17 @@ pub const BunTest = struct {
     first_last: BunTestRoot.FirstLast,
     extra_execution_entries: std.array_list.Managed(*ExecutionEntry),
     wants_wakeup: bool = false,
+    /// Stack of concurrent-sequence contexts whose JS callback is currently
+    /// being executed synchronously. Pushed by `Execution.stepSequenceOne`
+    /// before invoking `runTestCallback` and popped after it returns.
+    ///
+    /// During synchronous JS execution (including drained microtasks), the
+    /// top of this stack tells `getCurrentStateData` which concurrent
+    /// sequence the calling code belongs to, so `onTestFinished()` resolves
+    /// to the correct test. `expect.assertions()` / `expect.hasAssertions()`
+    /// / snapshot matchers intentionally do not use this stack — see
+    /// `expect.zig` for why they reject concurrent-test calls outright.
+    current_callback_stack: std.array_list.Managed(RefDataValue),
 
     phase: enum {
         collection,
@@ -253,6 +272,7 @@ pub const BunTest = struct {
             .default_concurrent = default_concurrent,
             .first_last = first_last,
             .extra_execution_entries = .init(this.gpa),
+            .current_callback_stack = .init(this.gpa),
         };
     }
     pub fn deinit(this: *BunTest) void {
@@ -268,6 +288,10 @@ pub const BunTest = struct {
             entry.destroy(this.gpa);
         }
         this.extra_execution_entries.deinit();
+        // every pushCurrentCallback must be paired with popCurrentCallback —
+        // a non-empty stack at teardown means we leaked a frame.
+        bun.debugAssert(this.current_callback_stack.items.len == 0);
+        this.current_callback_stack.deinit();
 
         this.execution.deinit();
         this.collection.deinit();
@@ -350,6 +374,16 @@ pub const BunTest = struct {
         return switch (this.phase) {
             .collection => .{ .collection = .{ .active_scope = this.collection.active_scope } },
             .execution => blk: {
+                // If a JS callback is currently executing synchronously (including
+                // during drained microtasks), the innermost push on
+                // `current_callback_stack` tells us exactly which sequence/entry
+                // we're inside. This disambiguates the concurrent case, where
+                // multiple sequences may be in-flight at the same time.
+                if (this.current_callback_stack.items.len > 0) {
+                    const top = this.current_callback_stack.items[this.current_callback_stack.items.len - 1];
+                    if (top == .execution) break :blk top;
+                }
+
                 const active_group = this.execution.activeGroup() orelse {
                     bun.debugAssert(false); // should have switched phase if we're calling getCurrentStateData, but it could happen with re-entry maybe
                     break :blk .{ .done = .{} };
@@ -384,6 +418,25 @@ pub const BunTest = struct {
             .done => .{ .done = .{} },
         };
     }
+
+    /// Push an entry onto the callback-execution stack. Must be paired with
+    /// `popCurrentCallback`. Call this immediately before invoking user JS
+    /// from a concurrent-safe context so nested hooks (`onTestFinished`,
+    /// `expect.assertions`) can recover which sequence they belong to.
+    pub fn pushCurrentCallback(this: *BunTest, data: RefDataValue) void {
+        bun.handleOom(this.current_callback_stack.append(data));
+    }
+
+    /// Pop the innermost callback-execution entry. Cheaply tolerates an
+    /// out-of-order pop during teardown — the only correct caller is the
+    /// defer that paired a preceding `pushCurrentCallback`.
+    pub fn popCurrentCallback(this: *BunTest) void {
+        if (this.current_callback_stack.items.len == 0) {
+            bun.debugAssert(false);
+            return;
+        }
+        _ = this.current_callback_stack.pop();
+    }
     pub fn ref(this_strong: BunTestPtr, phase: RefDataValue) *RefData {
         group.begin(@src());
         defer group.end();

src/bun.js/test/expect.zig

@@ -280,6 +280,12 @@ pub const Expect = struct {
         var buntest_strong = parent.bunTest() orelse return error.TestNotActive;
         defer buntest_strong.deinit();
         const buntest = buntest_strong.get();
+        // Snapshots in a concurrent group have the same limitation as
+        // `expect.assertions` — the sync call works, but a post-await call
+        // in the same test body can't resolve back to the right sequence.
+        // Reject at call time rather than silently writing to the wrong
+        // snapshot slot. See https://github.com/oven-sh/bun/issues/29236.
+        if (isInMultiSequenceConcurrentGroup(buntest)) return error.SnapshotInConcurrentGroup;
         const execution_entry = parent.phase.entry(buntest) orelse return error.SnapshotInConcurrentGroup;
 
         const test_name = execution_entry.base.name orelse "(unnamed)";
@@ -1178,18 +1184,39 @@ pub const Expect = struct {
         _ = callFrame;
         defer globalThis.bunVM().autoGarbageCollect();
 
-        var buntest_strong = bun.jsc.Jest.bun_test.cloneActiveStrong() orelse return globalThis.throw("expect.assertions() must be called within a test", .{});
+        var buntest_strong = bun.jsc.Jest.bun_test.cloneActiveStrong() orelse return globalThis.throw("expect.hasAssertions() must be called within a test", .{});
         defer buntest_strong.deinit();
         const buntest = buntest_strong.get();
+        if (isInMultiSequenceConcurrentGroup(buntest)) {
+            // expect.hasAssertions() and expect.assertions() can't work in
+            // concurrent tests: we can set the constraint on the calling
+            // sequence synchronously, but subsequent expect() matchers that
+            // resume after an `await` have no way to resolve back to the
+            // same sequence, so the counter diverges and the test ends with
+            // a spurious "expected N assertions" failure. Throw at call
+            // time instead of silently miscounting later.
+            return globalThis.throw("expect.hasAssertions() is not supported in concurrent tests. Remove `.concurrent` from the test or use `test.serial` instead.", .{});
+        }
         const state_data = buntest.getCurrentStateData();
-        const execution = state_data.sequence(buntest) orelse return globalThis.throw("expect.assertions() is not supported in the describe phase, in concurrent tests, between tests, or after test execution has completed", .{});
+        const execution = state_data.sequence(buntest) orelse return globalThis.throw("expect.hasAssertions() is not supported in the describe phase, between tests, or after test execution has completed", .{});
         if (execution.expect_assertions != .exact) {
             execution.expect_assertions = .at_least_one;
         }
 
         return .js_undefined;
     }
 
+    /// Returns true if the active execution group has more than one sequence
+    /// in flight (i.e. the caller is inside a `test.concurrent` group).
+    /// Used by `expect.assertions`/`expect.hasAssertions`, which can't safely
+    /// track per-sequence counters across `await` boundaries in a concurrent
+    /// group (see https://github.com/oven-sh/bun/issues/29236).
+    fn isInMultiSequenceConcurrentGroup(buntest: *bun.jsc.Jest.bun_test.BunTest) bool {
+        if (buntest.phase != .execution) return false;
+        const active_group = buntest.execution.activeGroup() orelse return false;
+        return active_group.sequences(&buntest.execution).len > 1;
+    }
+
     pub fn assertions(globalThis: *JSGlobalObject, callFrame: *CallFrame) bun.JSError!JSValue {
         defer globalThis.bunVM().autoGarbageCollect();
 
@@ -1218,8 +1245,14 @@ pub const Expect = struct {
         var buntest_strong = bun.jsc.Jest.bun_test.cloneActiveStrong() orelse return globalThis.throw("expect.assertions() must be called within a test", .{});
         defer buntest_strong.deinit();
         const buntest = buntest_strong.get();
+        if (isInMultiSequenceConcurrentGroup(buntest)) {
+            // Same limitation as `expect.hasAssertions` — see that function's
+            // comment for why we throw at call time instead of letting the
+            // per-sequence counter silently diverge across `await` boundaries.
+            return globalThis.throw("expect.assertions() is not supported in concurrent tests. Remove `.concurrent` from the test or use `test.serial` instead.", .{});
+        }
         const state_data = buntest.getCurrentStateData();
-        const execution = state_data.sequence(buntest) orelse return globalThis.throw("expect.assertions() is not supported in the describe phase, in concurrent tests, between tests, or after test execution has completed", .{});
+        const execution = state_data.sequence(buntest) orelse return globalThis.throw("expect.assertions() is not supported in the describe phase, between tests, or after test execution has completed", .{});
         execution.expect_assertions = .{ .exact = unsigned_expected_assertions };
 
         return .js_undefined;

test/js/bun/test/bun_test.test.ts

@@ -10,7 +10,13 @@ test("describe/test", async () => {
   });
   const exitCode = await result.exited;
   const stdout = await result.stdout.text();
-  const stderr = await result.stderr.text();
+  // ASAN builds unconditionally print a "WARNING: ASAN interferes with JSC
+  // signal handlers..." banner to stderr from WebKit's Options.cpp; strip it
+  // so the inline snapshot stays portable across sanitizer and release lanes.
+  const stderr = (await result.stderr.text())
+    .split(/\r?\n/)
+    .filter(s => !s.startsWith("WARNING: ASAN interferes"))
+    .join("\n");
   expect({
     exitCode,
     stdout: normalizeBunSnapshot(stdout),

test/js/bun/test/test-on-test-finished.test.ts

@@ -68,26 +68,30 @@ describe("async onTestFinished", () => {
   });
 });
 
-// Test that onTestFinished throws proper error in concurrent tests
-describe("onTestFinished errors", () => {
-  test.concurrent("cannot be called in concurrent test 1", () => {
-    expect(() => {
-      onTestFinished(() => {
-        console.log("should not run");
-      });
-    }).toThrow(
-      "Cannot call onTestFinished() here. It cannot be called inside a concurrent test. Use test.serial or remove test.concurrent.",
-    );
-  });
-
-  test.concurrent("cannot be called in concurrent test 2", () => {
-    expect(() => {
-      onTestFinished(() => {
-        console.log("should not run");
-      });
-    }).toThrow(
-      "Cannot call onTestFinished() here. It cannot be called inside a concurrent test. Use test.serial or remove test.concurrent.",
-    );
+// https://github.com/oven-sh/bun/issues/29236 — onTestFinished() is
+// callable from inside a concurrent test. Each sequence accumulates its
+// own hooks and runs them at the end of that sequence.
+describe("onTestFinished in concurrent tests", () => {
+  const a_output: string[] = [];
+  const b_output: string[] = [];
+
+  test.concurrent("test a", () => {
+    onTestFinished(() => {
+      a_output.push("a-finished");
+    });
+    a_output.push("a-body");
+  });
+
+  test.concurrent("test b", () => {
+    onTestFinished(() => {
+      b_output.push("b-finished");
+    });
+    b_output.push("b-body");
+  });
+
+  test("verify each sequence ran its own hook", () => {
+    expect(a_output).toEqual(["a-body", "a-finished"]);
+    expect(b_output).toEqual(["b-body", "b-finished"]);
   });
 });