feat(runner): propagate AsyncLocalStorage context from fixtures into tests and hooks

[VialFlorian]

Description

Fixtures created with test.extend deliver their value through a deferred use() handshake, so an AsyncLocalStorage context established around use() never reached the test body:

const test = baseTest.extend({
  store: async ({}, use) => {
    const store = { tenant: 'alpha' }
    await als.run(store, () => use(store))
  },
})

test('reads the store', () => {
  als.getStore() // undefined before this PR
})

This PR captures an async context snapshot inside each test-scoped fixture's use() and enters later fixtures, beforeEach/afterEach, onTestFinished/onTestFailed, beforeEach cleanup callbacks and the test body through the latest capture. The fixture handshake, teardown ordering and caching are untouched.

What this enables

Per-test stores become trivial to set up (the pattern that motivated this change)
An app whose code reads a request-scoped store (loggers, tenant config, DB clients) can give every test its own isolated store, with per-test overrides, no visible wrapper, and full support for .only/.skip/.each/test.concurrent:

const base = baseTest.extend<{ override: Partial<Store>, store: Store }>({
  override: {},
  store: [
    async ({ override }, use) => {
      const store = { tenant: 'main', logger: mockLogger(), ...override }
      await als.run(store, () => use(store))
    },
    { auto: true },
  ],
})

// one line of userland turns this into a per-test API
const it = Object.assign(base, {
  withStore: (override: Partial<Store>) => base.extend({ override }),
})

it('uses the default store', ({ store }) => {
  expect(als.getStore().tenant).toBe("main")
})

it.withStore({ tenant: 'acme' })('configures its own store, independently', ({ store }) => {
  expect(als.getStore().tenant).toBe("acme")
  expect(store.logger.warn).toHaveBeenCalled()  // per-test logger assertions
})

Each test keeps its own store even under test.concurrent. Today this requires a custom it-wrapper helper that loses the chainable API, or is simply impossible where hooks and dependent fixtures must see the store too.

Revisiting #5858

This revisits #5858, which was closed in 2024 as intentional ("Fixtures initialization runs separately from test execution") and redirected to #5728, since resolved by aroundEach/aroundAll in 4.1. aroundEach wraps each test of a suite in a store and aroundAll can span one store across a whole suite or file, but the fixture form remains the natural way to model per-test context with overrides and composition. The test.extend API is modeled on Playwright's fixtures; note that Playwright does not propagate the store from fixtures either (verified with a small repro), so this is new capability rather than parity. The approach here did not exist in that discussion: it does not restructure fixture resolution into call nesting, it only re-enters a frame captured at use() time, so the change is small and strictly additive.

Related: #5858, #5728

Design notes

• Only test-scoped fixtures propagate their store. Entering a snapshot replaces the whole async frame, so a chain kept for a file/worker-scoped fixture would leak the resolving test's ambient context into other tests and erase aroundAll stores. Scoped fixtures keep propagating their value only (tested and documented).
• Browsers are unaffected. The snapshot factory is injected from the Node-only worker entry; when it is not set, every helper degrades to a plain call.
• No observable change without fixtures. Pipelines that never resolve a fixture never enter a snapshot, keeping error stack traces byte-identical (locked by the existing aroundEach e2e snapshots).
• The snapshot is a named AsyncResource that detectAsyncLeaks ignores, and aroundEach/aroundAll stores compose with fixture stores (covered by the new e2e suite).

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed. (References Async context is not passed into tests from fixtures #5858/Add aroundEach Hook Similar to RSpec around #5728 — see "Revisiting Async context is not passed into tests from fixtures #5858"; can open a fresh discussion first if preferred.)
• Ideally, include a test that fails without this PR but passes with it. (The new test/e2e/test/fixture-async-context.test.ts suite fails on main.)
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
• Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command. (New "Fixtures and AsyncLocalStorage" section in the Test Context guide.)

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

[netlify]

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	5700932
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/6a7e4afd6f03ad00090be9cc
😎 Deploy Preview	https://deploy-preview-10858--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[VialFlorian]

Confirming I'm the author and maintaining this PR (built with AI assistance)

I'm already using this in a private codebase, where the test suite runs every test concurrently, each inside its own AsyncLocalStorage store. Happy to open an issue first or gate this behind an option if preferred 🙂

[sheremet-va]

I am confused how aroundEach establishes a store for a whole suite or a file. It runs once per test, not suite or a file

[VialFlorian]

Yes indeed, I have updated to make it more clear

To set up a store around each test of a suite, register an [`aroundEach`](/api/hooks#aroundeach) hook; to open a single store spanning every test in a suite or file, use [`aroundAll`](/api/hooks#aroundall).

[hi-ogawa]

but the fixture form remains the natural way to model per-test context with overrides and composition (it is how Playwright fixtures behave, which this API is modeled on).

Do you mean playwright fixture also does something similar now with AsyncLocalStorage?

[VialFlorian]

but the fixture form remains the natural way to model per-test context with overrides and composition (it is how Playwright fixtures behave, which this API is modeled on).

Do you mean playwright fixture also does something similar now with AsyncLocalStorage?

@hi-ogawa No, I assumed it did and that was wrong. I checked with a small repro: a Playwright fixture doing await als.run(store, () => use(store)) delivers the value to the test, but als.getStore() is undefined in the test body (the same deferred use() behavior Vitest has before this PR)

import { AsyncLocalStorage } from 'node:async_hooks'
import { test as base } from '@playwright/test'

const als = new AsyncLocalStorage<{ id: string }>()

const test = base.extend<{ store: { id: string } }>({
  store: async ({}, use) => {
    const store = { id: 'from-fixture' }
    await als.run(store, () => use(store))
  },
})

test('als propagation', async ({ store }) => {
  console.log(store.id, als.getStore()) // "from-fixture" undefined
})

I've corrected the description: the test.extend API is modeled on Playwright's fixtures, but neither runner propagates the store today, so this would be new capability rather than parity.

[hi-ogawa]

The idea looks sound to me. Still digesting but I have thought of some tests cases that looks worth recording:

---

1. For non auto fixture, the async context becomes available only after fixture execution, so something like this happens:

const test = base.extend({ fixture: () => ...als.run... })
beforeEach(() => als.getStore())       // undefined
test(({ fixture }) => als.getStore()) // fixture store
afterEach(() => als.getStore())       // fixture store

2. without explicit inter-fixture dependency, each fixture runs still construct each "chained" async context:

const test = base.extend({
  fixture1: () =>  ...als1.run...,
  fixture2: () => ...als2.run..., // since fixture1 runs before fixture2, so als1 store is available
})
test({ fixture1, fixture2 }) => als1.getStore(), als2.getStore()) // both stores available

[hi-ogawa]

I'm still in favor of this feature but found another test case to illustrate the "non composable" nature of runInAsyncScope itself. So making it look like composable does require Vitest internal to coordinate snapshot/restore properly (like especially for aroundEach). It may look too surgical, but I think it's worth tracking as test case.

Custom runTask example

test('fixture snapshots preserve contexts established by a custom runTask', async () => {
  const { errorTree } = await runInlineTests({
    'vitest.config.ts': `
      export default {
        test: {
          runner: './runner.ts',
        },
      }
    `,
    'storage.ts': `
      import { AsyncLocalStorage } from 'node:async_hooks'

      const key = Symbol.for('vitest.custom-runner-storage')
      export const runnerStorage: AsyncLocalStorage<string>
        = (globalThis as any)[key] ??= new AsyncLocalStorage<string>()
    `,
    'runner.ts': `
      import type { RunnerTask } from 'vitest'
      import { TestRunner } from 'vitest'
      import { runnerStorage } from './storage'

      export default class CustomRunner extends TestRunner {
        async runTask(test: RunnerTask): Promise<void> {
          const fn = CustomRunner.getTestFn(test)
          await runnerStorage.run('runner', () => fn())
        }
      }
    `,
    'custom-runner.test.ts': `
      import { AsyncLocalStorage } from 'node:async_hooks'
      import { beforeEach, expect, test as base } from 'vitest'
      import { runnerStorage } from './storage'

      const fixtureStorage = new AsyncLocalStorage<string>()
      const test = base.extend({
        fixture: [
          async ({}, use) => fixtureStorage.run('fixture', () => use('fixture')),
          { auto: true },
        ],
      })

      // This causes the auto fixture snapshot to be captured before runTask.
      beforeEach(() => {})

      base('preserves the runner context without fixtures', () => {
        expect(runnerStorage.getStore()).toBe('runner')
      })

      test('loses the runner context with fixtures', () => {
        expect(fixtureStorage.getStore()).toBe('fixture')
        expect(runnerStorage.getStore()).toBe('runner')
      })
    `,
  })

  expect(errorTree()).toMatchInlineSnapshot(`
    {
      "custom-runner.test.ts": {
        "loses the runner context with fixtures": [
          "expected undefined to be 'runner' // Object.is equality",
        ],
        "preserves the runner context without fixtures": "passed",
      },
    }
  `)
})

[hi-ogawa]

Is top level code only way? I think it may be more natural to coordinate some runner related init phase somehow.

[VialFlorian]

No, I can move it into resolveTestRunner, or do you have something else in mind?

[hi-ogawa]

I don't think this rewriting name advanceAsyncContext/refreshAsyncContextChain is called for. Can be just refreshAsyncContextChain all the way.

[hi-ogawa]

We want also another variant where aroundEach overrides same ALS as fixture. I initially had an mislead impression that refreshAsyncContextChain would make it non overridable but it would actually work fine.