Skip to content
Logo

Runners

Harness works with any runner that has a Jest-style describe, it, and expect: bun, vitest, rstest, jest, mocha, and node:test. You pass the runner's module to initialize, and harness never imports one itself.

import * as framework from "bun:test"; // or "vitest", "@jest/globals", …

Harness needs an expect on the module. mocha and node:test have none, so add one, such as the standalone expect package:

import { expect } from "expect";
import * as runner from "node:test";
 
const framework = { ...runner, expect };

To check that your runner, at your version, behaves the way harness needs, run the conformance suite.

What's wrapped

Harness wraps describe, it, and test, and these modifiers on them:

  • .only, .skip, .todo, .failing, and .concurrent, forwarded to the runner.
  • .skipIf(condition), .todoIf(condition), and .failingIf(condition), which pick the modified or unmodified form.
  • .each, built by harness. See .each.

And the hooks: beforeEach and afterEach (run by harness), and beforeAll and afterAll (forwarded). See Hooks.

Only what your runner has

The wrapped API is typed from your runner's own types, and offers a forwarded modifier only where the runner has it:

  • it.failing is missing on vitest and rstest, which call it fails.
  • describe.todo is missing on jest.
  • On node:test and mocha, a modifier can't be chained with another.
  • beforeAll and afterAll are missing on a runner without them.

.each, beforeEach, and afterEach are built by harness, so they're always there.

The *If forms appear only when the runner has a modifier that can carry them out: skipIf and todoIf need skip or todo, and failingIf needs failing. If a runner's types promise one its runtime doesn't have, calling it throws ModifierUnsupportedError rather than running a test you meant to skip.

Where a runner's types claim more than it does at runtime, harness inherits that. It doesn't add claims of its own.

Test bodies

  • A test body takes one argument, the context. done callbacks aren't supported, as in vitest.
  • Arguments after the body, like a timeout, are passed to the runner unchanged.
  • Mocha's this reaches your test and describe callbacks, so this.timeout(), this.retries(), and this.skip() work. Use a function, not an arrow, as mocha requires.

The escape hatch

initialize also returns framework, the unchanged module. Use it for what harness doesn't wrap, like the runner's own hooks or runner-specific matchers. Don't group tests with framework.describe: harness doesn't see it, so the name drops out of the tests' identity. See Test identity.

expect is the runner's own, bound so that destructuring it works on runners that implement it as a method.