test: migrate backend and scripts to bun test runner (#2184)

* test: migrate backend and scripts to bun test runner

Retire Jest for the backend and scripts suites in favor of Bun's runner,
driven by a per-file-process launcher over one shared in-memory MongoDB
replica set. Restores Jest-like per-file isolation without per-file startup.

- 3-run medians: backend 43.5s -> 11s (-74%), scripts 52.4s -> 14.7s (-72%).
- Remove jest, @shelf/jest-mongodb, jest-environment-node, @babel/*, and their
  config; add mongodb-memory-server. @types/jest kept (type annotations only).
- Retire the six permanently-completed 2025 migration integration suites; add a
  fast discovery/ordering guard and a migration baseline README. All migration
  implementations and transforms are retained (still used by provisioning/web).
- Mongo test lifecycle: no production backoff under test env, one shared server,
  cleanupTestDb no longer disconnects.
- Bun compat fixes: bun:test imports (never jest), requireActual snapshot to
  stop mutate-after-mock recursion, lazy mockRejectedValue, stable-per-name
  winston mock, mutable compassTestState, .resolves.toBeUndefined().
- Test tiers (fast/db/migrations, auto-classified) and CI mongod binary cache.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(scripts): tighten migration-discovery guard and runner teardown

- Drop a tautological assertion in migration-discovery.test.ts that compared
  a lexicographic sort to itself (always true); keep the meaningful
  timestamp-prefix and name-uniqueness checks that actually guard Umzug's order.
- Wrap the launcher's run in try/finally so the in-memory mongod is always
  stopped even if a worker throws.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(scripts): declare @sinonjs/fake-timers for the bun compat shim

The jest->bun compat shim requires @sinonjs/fake-timers, previously satisfied
transitively via jest. Removing jest orphaned it, so a frozen-lockfile install
in CI could no longer resolve it and every unit job that loads the shim (core,
web, backend, scripts) failed. Declare it explicitly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(backend): import lifecycle hooks in preload helpers from bun:test

backend.test.start and mock.setup registered global beforeEach/afterAll via
Bun's injected test globals. From a preloaded (dynamically imported) module that
injection is racy -- one CI run intermittently failed with "afterEach is not
defined" while the same commit passed elsewhere and always passed locally.
Import the hooks explicitly so registration never depends on injection timing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(backend): apply bun test conversions to merged event.service tests

Main's cross-calendar-move suite (#2183) landed after this branch forked. Apply
the same bun:test conversions to it: import afterEach explicitly (Bun disables
injected globals once a file imports from bun:test) and make the rejected mock
lazy so Bun doesn't flag an eager unhandled rejection.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: tyler-dane

.github/workflows/test-unit.yml

@@ -117,6 +117,15 @@ jobs:
         run: |
           bun install --frozen-lockfile
 
+      # backend and scripts boot an in-memory MongoDB; cache the downloaded
+      # mongod binary so each run doesn't re-fetch it.
+      - name: Cache MongoDB binaries
+        if: matrix.project == 'backend' || matrix.project == 'scripts'
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/mongodb-binaries
+          key: ${{ runner.os }}-mongodb-memory-server
+
       - name: Run web tests
         if: matrix.project == 'web'
         timeout-minutes: 1
@@ -127,6 +136,7 @@ jobs:
 
       - name: Run ${{ matrix.project }} tests
         if: matrix.project != 'web'
+        timeout-minutes: 5
         env:
           TZ: Etc/UTC
         run: |

babel.config.js

@@ -104,7 +104,8 @@ Use this document to find the first files to inspect for common Compass changes.
 
 ## Test Anchors
 
-- Retained Jest project config for `web`, `backend`, and `scripts`: `jest.config.js`
+- Mongo-backed test launcher (per-file isolation over one in-memory replica set): `packages/scripts/src/testing/run-tests.ts`
+- Bun/Jest compatibility shim used by every package's tests: `packages/scripts/src/testing/apply-bun-jest-compat.cjs`
 - Core test setup: `packages/core/src/__tests__`
 - Web test setup: `packages/web/src/__tests__`
 - Web mock server handlers: `packages/web/src/__tests__/__mocks__/server/mock.handlers.ts`

bun.lock

@@ -17,13 +17,10 @@ never pay for it.
 
 ```bash
 # normal run -- confirms the bench suite shows as skipped
-TZ=UTC ./node_modules/.bin/jest --selectProjects backend
+bun run test:backend
 
 # the real run -- prints one `[bench]` summary line per scenario.
-# (--testPathPattern is load-bearing: a bare trailing "bench" arg is
-# consumed by --selectProjects as a nonexistent project name and the
-# whole suite runs instead.)
-RUN_BENCH=1 TZ=UTC ./node_modules/.bin/jest --selectProjects backend --testPathPattern="bench"
+RUN_BENCH=1 bun packages/scripts/src/testing/run-tests.ts backend --filter bench
 ```
 
 ### Last recorded numbers

docs/development/feature-file-map.md

@@ -44,24 +44,20 @@ E2E workflow (`test-e2e.yml`) is separate and runs on pull requests to `main` vi
 
 ## Current Test Strategy
 
+Every package now runs on Bun's test runner; Jest has been removed.
+
 - `bun run test:core` uses `bun test` with a small compatibility preload for the core BSON mock setup.
 - `bun run test:web` runs `bun test --cwd packages/web` directly. Web tests should be isolated enough to run in one Bun process without batching.
-- `bun run test:backend` and `bun run test:scripts` intentionally retain the existing Jest harness while their hoist-heavy module-mocking patterns are migrated.
-
-## Retained Jest Layout
-
-Source:
-
-- `jest.config.js`
-
-Projects:
+- `bun run test:backend` and `bun run test:scripts` use `packages/scripts/src/testing/run-tests.ts`, a launcher that boots one in-memory MongoDB replica set and runs each test file in its own `bun test` process (Jest-like per-file isolation) against the shared server, in parallel. This keeps the isolation Jest gave us without its per-file startup cost.
+- Test files import lifecycle/assertion APIs from `bun:test` (never `jest` -- the ambient `jest` global is a compatibility shim from `packages/scripts/src/testing/apply-bun-jest-compat.cjs` that maps `jest.mock`/`jest.requireActual`/etc. onto `bun:test`).
 
-- `core`
-- `web`
-- `backend`
-- `scripts`
+### Test tiers
 
-Each project has its own setup files and module alias mapping.
+- `bun run test:backend` / `bun run test:scripts` -- the full package suite.
+- `bun run test:backend:fast` / `bun run test:scripts:fast` -- only files that never touch Mongo (auto-classified: no `setupTestDb`).
+- `bun run test:backend:db` / `bun run test:scripts:db` -- only the Mongo-backed files.
+- `bun run test:migrations` -- the active migration suites under `packages/scripts/src/migrations`.
+- Focus a run with `--filter <substring>`, e.g. `bun packages/scripts/src/testing/run-tests.ts backend --filter user.controller`.
 
 ## What To Run By Change Type
 
@@ -261,7 +257,7 @@ This keeps tests on production code paths while avoiding brittle layout coupling
 
 ### Jest Unbound-Method Rule In Tests
 
-Test linting enforces `jest/unbound-method`. If you need to assert method calls on non-mock objects, spy on the method first so assertions are bound to a Jest mock/spy.
+If you need to assert method calls on non-mock objects, spy on the method first (`jest.spyOn(...)`, backed by `bun:test`) so the assertion is bound to a real mock/spy rather than an unbound method reference.
 
 Useful anchors:
 
@@ -279,7 +275,7 @@ Preferred style:
 
 **Do not import `mongoService` (or other persistence implementations) directly in tests.** Use test drivers instead (e.g. `UserDriver`, `GoogleWatchDriver` in `packages/backend/src/__tests__/drivers/`). Drivers encapsulate persistence so that switching away from Mongo (or another store) in the future does not require changing test code.
 
-CI runs every lane with `TZ: Etc/UTC` (see CI Unit Test Workflow above). If a backend test only fails locally, match that explicitly rather than relying on your machine's default timezone: `TZ=UTC ./node_modules/.bin/jest --selectProjects backend`.
+CI runs every lane with `TZ: Etc/UTC` (see CI Unit Test Workflow above). The launcher already sets `TZ=Etc/UTC` for each test process, so a backend test that only fails locally is rarely a timezone issue; to reproduce CI exactly, run `bun run test:backend`.
 
 Useful anchors: