Skip to content
Logo

Hooks

Harness wraps all four hooks, but runs them two different ways. beforeAll and afterAll are registered with your runner as usual. beforeEach and afterEach are not: harness runs them itself, inside each test.

beforeEach and afterEach run inside the test

A wrapped it runs the beforeEach hooks of every enclosing describe, then the body, then the afterEach hooks, all inside the test's integration frames. So hooks get the same context object as the body:

describe("orders", () => {
  beforeEach(async ({ db }) => {
    await db.insert(customers).values({ id: 1 });
  });
 
  it("places an order", async ({ db }) => {
    // the same transaction the beforeEach used
  });
});

Every scope an integration opens is live in all three, and setup runs before every beforeEach while teardown runs after every afterEach. Since the context object is shared, a beforeEach can leave a key of its own for the body:

beforeEach((context) => {
  Object.assign(context, { user: makeUser() });
});

beforeEach hooks run outermost describe first, and afterEach hooks run innermost first. A beforeEach declared after an it in the same describe still applies to it, as it does in every runner. afterEach runs even when a beforeEach or the body threw.

beforeEach and afterEach are always available, even on a runner without hooks of its own.

What that costs

Running hooks inside the test changes a few things compared with your runner's own hooks:

  • A failing beforeEach or afterEach is reported as a test failure, not a hook failure.
  • Hook time counts against the test's timeout.
  • Hooks don't take the runner's per-hook options, like a timeout.
  • A wrapped beforeEach always runs inside any framework.beforeEach, whatever order you declared them in.
  • A skipped or todo test has no body to run, so its hooks don't run either. That matches the runner.

If you need the runner's own behavior, use framework.beforeEach and framework.afterEach. Those get no context.

Hooks need a suite

A beforeEach or afterEach at the top of a file throws AmbientHookError. There's no suite to attach it to, and with one shared setup module, Bun would run it for every test in every file. Put it inside a describe.

The same error covers a hook called after an await in an async describe. Take it from the suite's scope instead. See Async describe.

beforeAll and afterAll run per suite

beforeAll and afterAll are registered with your runner and keep its behavior and options. Each call runs inside the integration frames with a suite identity:

{ kind: "suite", path: ["orders"], name: "", row: undefined }

So integrations give a beforeAll its own per-suite state, separate from every test under it. A beforeAll and an afterAll in the same describe share one identity on purpose.

The frame lasts for one hook call. It closes when the beforeAll returns, and it doesn't wrap the suite's tests. What a beforeAll sets up for the tests, it has to store itself, as with any runner.

These two are only there when your runner has them.