avajs/ava · error · AssertionError

`t.snapshot()` can only be used in tests

Error message

`t.snapshot()` can only be used in tests

What it means

AVA's t.snapshot() records/compares snapshot files, but snapshots are only enabled inside test runs where a snapshot manager is wired up. When the assertion runs in a context where snapshots are disabled (e.g. inside a worker without snapshot support, or a custom/non-test execution context), AVA throws this AssertionError to prevent writing snapshots incorrectly.

Source

Thrown at lib/assert.js:636

					assertion: 't.notThrowsAsync()',
					cause: error,
					formattedDetails: [formatWithLabel('Function threw:', error)],
				}));
			}

			if (!isPromise(retval)) {
				throw fail(new AssertionError(message, {
					assertion: 't.notThrowsAsync()',
					formattedDetails: [formatWithLabel('Function did not return a promise. Use `t.notThrows()` instead:', retval)],
				}));
			}

			return handlePromise(retval, true);
		});

		this.snapshot = withSkip((expected, message) => {
			if (disableSnapshots) {
				throw fail(new AssertionError('`t.snapshot()` can only be used in tests', {
					assertion: 't.snapshot()',
				}));
			}

			assertMessage(message, 't.snapshot()');

			if (message === '') {
				throw fail(new AssertionError('The snapshot assertion message must be a non-empty string', {
					assertion: 't.snapshot()',
					formattedDetails: [formatWithLabel('Called with:', message)],
				}));
			}

			let result;
			try {
				result = compareWithSnapshot({expected, message});
			} catch (error) {
				if (!(error instanceof SnapshotError)) {

View on GitHub (pinned to bbfd946322)

Solutions

1. Only call t.snapshot() inside regular test bodies executed by AVA
2. Move snapshot assertions out of shared helpers/hooks into test bodies
3. If the code must run outside tests, gate it: only snapshot when the context supports it
4. Update AVA if using an older version with different snapshot context rules

Example fix

// before
// shared helper called from tests and scripts
export function verify(t, value) {
  t.snapshot(value);
}
// after
export function verify(t, value) {
  if (typeof t.snapshot === 'function' && t.snapshotEnabled !== false) {
    t.snapshot(value);
  } else {
    t.deepEqual(value, expectedValue);
  }
}

// Only snapshot in AVA test bodies, never in shared helpers invoked outside tests:
if (typeof t.snapshot !== 'function' || snapshotsDisabled) {
  t.deepEqual(actual, expected); // fallback assertion
} else {
  t.snapshot(actual);
}

const canSnapshot = (t) => typeof t.snapshot === 'function' && !t.snapshotDisabled;

try {
  t.snapshot(value);
} catch (e) {
  if (/can only be used in tests/.test(e.message)) {
    t.deepEqual(value, expected);
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling t.snapshot() in code shared between tests and non-test contexts where the assertion context was created with snapshots disabled; using t.snapshot() in setup/teardown helpers or in AVA's experimental contexts that disallow it; invoking test file code outside `ava` (e.g. via node directly) with a manually constructed assertion context.

Common situations: Shared assertion utilities used by both unit tests and scripts; running test files under a different runner or bundler that bypasses AVA's snapshot setup; snapshot assertions inside hooks or sub-workflows where the disableSnapshots flag is true.

Related errors

• `t.notThrows()` must be called with a function
• `t.notThrowsAsync()` must be called with a function or promi
• The `any` property of the second argument to `${assertion}`
• The second argument to `${assertion}` contains unexpected pr
• message

AI-assisted analysis of avajs/ava@bbfd946322 (2026-09-02). Data as JSON: /api/errors/82ee010691843758. Report an issue: GitHub.