vitest-dev/vitest · error · Error

'${getAssertionName(obj)}' cannot be used without test conte

Error message

'${getAssertionName(obj)}' cannot be used without test context

What it means

Every snapshot matcher resolves the current `Test` via the `vitest-test` chai flag (through `getTest`) to obtain filepath, test id, and test name used as the snapshot key. If no test is bound — because the matcher runs outside any `it`/`test` — there is no context to key the snapshot against, so it throws `'<name>' cannot be used without test context`.

Source

Thrown at packages/vitest/src/integrations/snapshot/chai.ts:68

  return {
    filepath: test.file.filepath,
    name: getNames(test).slice(1).join(' > '),
    testId: test.id,
  }
}

function getAssertionName(assertion: Chai.Assertion): string {
  const name = chai.util.flag(assertion, '_name') as string | undefined
  if (!name) {
    throw new Error('Assertion name is not set. This is a bug in Vitest. Please, open a new issue with reproduction.')
  }
  return name
}

function getTest(obj: Chai.Assertion) {
  const test = chai.util.flag(obj, 'vitest-test') as Test | undefined
  if (!test) {
    throw new Error(`'${getAssertionName(obj)}' cannot be used without test context`)
  }
  if (test.fails) {
    throw new TestSyntaxError(`'${getAssertionName(obj)}' cannot be used with 'test.fails'`)
  }
  return test
}

function validateAssertion(assertion: Chai.Assertion): void {
  if (chai.util.flag(assertion, 'negate')) {
    throw new Error(`${getAssertionName(assertion)} cannot be used with "not"`)
  }
}

export const SnapshotPlugin: ChaiPlugin = (chai, utils) => {
  for (const key of ['matchSnapshot', 'toMatchSnapshot']) {
    utils.addMethod(
      chai.Assertion.prototype,
      key,

View on GitHub (pinned to d568f8ce37)

Solutions

1. Move the snapshot assertion inside an `it()`/`test()` body.
2. For setup-time checks, capture the value in the hook and assert on it inside the test.
3. If writing a custom matcher, ensure it is invoked from within a test so the context is present.

Example fix

// before (module scope)
const data = loadData()
expect(data).toMatchSnapshot()
// after
it('matches snapshot', () => {
  expect(loadData()).toMatchSnapshot()
})

import { getWorkerState } from 'vitest'
function assertInTest() {
  if (!getWorkerState().current) throw new Error('snapshot matchers require an active test')
}

When it happens

Trigger: Calling `toMatchSnapshot`/`toMatchInlineSnapshot`/`toMatchFileSnapshot`/`toThrowErrorMatchingSnapshot`/`toThrowErrorMatchingInlineSnapshot` (and the domain variants) at module top level, inside hooks, or in a standalone script with no active test.

Common situations: Hoisting a snapshot assertion into a helper invoked outside a test, or running the expect API outside the Vitest runner.

Related errors

• expected must be a function, received ${typeof expected}
• snapshot function didn't throw
• You must provide an array or set to ${matcherHint('.toBeOneO
• Snapshot cannot be used outside of test
• Received value must be an object when the matcher has proper

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/e4f6733187030be1.json. Report an issue: GitHub.