Jest Test Infrastructure#

matrix-js-sdk uses Jest (v29) as its test runner, with Babel transpilation to handle TypeScript and ESM source code. All tests live under spec/ and are split into two named suites — unit and integ — which run as separate CI matrix legs.

Configuration#

The root jest.config.ts defines the shared configuration:

Setting	Value	Notes
`testEnvironment`	`node`
`testMatch`	`spec/*/.spec.{js,ts}`	Picks up all `.spec.ts` / `.spec.js` files under `spec/`
`setupFilesAfterEnv`	`spec/setupTests.ts`	Runs once per worker after the test framework is installed
`collectCoverageFrom`	`src/*/.{js,ts}`	Only measures coverage over production source
`coverageReporters`	`text-summary`, `lcov`	LCOV output is uploaded to SonarCloud
`testResultsProcessor`	`@casualbot/jest-sonar-reporter`	Emits a Sonar-compatible XML report to `coverage/`

In CI, the reporter list is overridden to use github-actions for inline PR annotations. On the develop branch specifically, spec/slowReporter.cjs is also added, which logs the top-N slowest tests and suites at the end of the run .

Babel Transpilation#

Because the project ships as ES modules but Jest does not fully support ESM, babel.config.cjs switches to CommonJS output when NODE_ENV === "test" . Import extensions are not rewritten under Jest (i.e., .ts source paths are used as-is rather than being rewritten to .js) . The babel-jest transform is the mechanism that wires this up .

Test Layout#

spec/
  unit/ # Isolated unit tests, ~54 files/dirs including crypto, stores, models
  integ/ # Integration tests against a mock Matrix server, ~13 files
  test-utils/ # Shared helpers, mocks, and test data
  setupTests.ts
  slowReporter.cjs

spec/unit/ — fast, isolated tests with no network I/O
spec/integ/ — tests that exercise the full MatrixClient event/sync lifecycle against mocked HTTP
spec/test-utils/ — shared utilities (TestClient, MockStorageApi, mock event factories, etc.)

Setup File#

spec/setupTests.ts does two things:

Mocks timeoutSignal() (from HTTP API utils) to return a plain AbortController signal, preventing dangling timers from leaking between tests .
Extends Jest timeout to 5 minutes when running inside the VS Code debugger (detected via VSCODE_INSPECTOR_OPTIONS), so breakpoints don't cause spurious test failures .

npm Scripts#

Defined in package.json:

Script	Command
`yarn test`	`jest` (all specs)
`yarn test:watch`	`jest --watch`
`yarn coverage`	`jest --coverage`

Pass any Jest CLI args or a path suffix to scope to a specific suite: e.g., yarn test ./spec/unit.

CI Matrix#

The tests.yml workflow runs on every PR, push to develop/master, and merge-queue entry. It fans out over a 2 × 2 matrix — {unit, integ} × {Node LTS, Node 22} — with a 10-minute timeout per leg .

Key CI behaviors:

Coverage is disabled in merge queues (ENABLE_COVERAGE is false when github.event_name == 'merge_group') to keep merge-queue runs fast .
Each enabled-coverage run renames its LCOV file to include the Node version and suite name (e.g., 22-unit.lcov.info) before uploading .
A jest-complete dummy job aggregates all matrix legs for branch-protection rules .
On merge-queue events, downstream tests are also triggered: element-web and complement-crypto.