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.

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…
• Cannot record snapshot
• Could not compare snapshot
• Did not match snapshot

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

Appendix: 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)