Bun’s built-in test runner is Jest-like but not identical. A suite that passed under Jest can fail or hang under bun test because of API differences, a missing preload/setup, or async tests exceeding the default timeout.
What this error means
bun test fails with undefined test globals/matchers, an unloaded setup file, or tests that hang until the timeout. The same tests may pass under Jest, which points at a runner difference, not a logic bug.
bun output
error: Cannot find name 'jest'. Did you mean 'Bun'?
# or
1 tests timed out after 5000ms
at test/api.test.ts:12
Diagnose it: which runtime is actually on PATH?
Runners ship multiple versions of most runtimes and select one through a version manager. When a setup action and a version file disagree, the resulting error is about your code rather than the version.
Terminal
which -a <runtime>
<runtime> --version
echo "PATH=$PATH" | tr ":" "\n" | head -20
# does a version file in the repo disagree with the workflow?
cat .tool-versions .nvmrc .ruby-version .python-version 2>/dev/null
Common causes
Jest-specific APIs or globals
Bun implements much of the Jest API but not all of it. Code relying on Jest-only globals/matchers or config can fail under Bun’s runner.
Missing preload/setup or short timeout
A setup file (mocks, env) configured for Jest is not loaded by Bun unless declared, and Bun’s default test timeout can be shorter than a slow async test needs.
How to fix it
Use Bun’s test API and preload setup
Import from bun:test and declare a preload in bunfig.toml so setup runs.
bun:test / bunfig.toml
// import from bun:test
import { test, expect, beforeAll } from "bun:test";
// bunfig.toml
[test]
preload = ["./test/setup.ts"]
Raise the timeout for slow tests
Terminal
bun test --timeout 20000
# or per test:# test("slow", async () => { ... }, 20000)
How to prevent it
Import test helpers from bun:test rather than relying on Jest globals.
Declare setup files via bunfig.toml[test] preload.
Set realistic timeouts for async/integration tests.
Frequently asked questions
What causes Bun "bun test" fails or hangs in CI?
There are 2 common causes: jest-specific apis or globals and missing preload/setup or short timeout. Bun implements much of the Jest API but not all of it.
How do I fix Bun "bun test" fails or hangs in CI?
There are 2 fixes depending on which cause you have: use bun’s test api and preload setup and raise the timeout for slow tests. Work through them in order, since the first is the most common.
What does Bun "bun test" fails or hangs in CI actually mean?
bun test fails with undefined test globals/matchers, an unloaded setup file, or tests that hang until the timeout.
How do I stop Bun "bun test" fails or hangs in CI happening again?
Import test helpers from bun:test rather than relying on Jest globals. The prevention section lists 3 changes that keep it from recurring.
