Vitest Testing

Use the tdd skill when the task is a logic change or bug fix that should start with a failing test. This skill covers Vitest-specific test shape and review rules.

Setup

• Check vitest.config.* before assuming globals are enabled.
• If globals are enabled, use describe, it, expect, vi, beforeEach, and assert directly without importing them.
• If globals are not enabled, import only the Vitest APIs used by the file.
• Avoid await import() and other dynamic imports in tests unless the behaviour under test is dynamic loading.
• Use vi.stubEnv() instead of mutating process.env directly.

Readability

• Test one behaviour per it.
• Name tests after observable behaviour, not implementation details.
• Avoid try/catch for expected failures. Use expect(...).toThrow(), await expect(...).rejects, or explicit Result failure assertions.
• Avoid if branches inside test bodies. Split behaviours into separate tests or use it.each for table-driven cases.
• KISS > DRY: do not over-DRY tests. Keep repeated setup inline when it makes the behaviour easier to read.
• Keep assertions in the test unless a helper name is clearer than the assertion it hides.
• Use assert to make preconditions explicit and narrow nullable values instead of using non-null assertions.

Output Tests

• Prefer JSON assertions for structured behaviour.
• Use file snapshots with toMatchFileSnapshot for human-readable CLI/table output so layout changes are reviewable.
• For responsive terminal output, capture or set the terminal width used by the command.

Examples

Expected failure:

it('rejects invalid config', async () => {
	await expect(loadConfig('bad.json')).rejects.toThrow(Error);
});

Table-driven case:

it.each([
	['daily', '2026-05-16'],
	['monthly', '2026-05'],
])('groups %s rows by period', (reportType, expectedPeriod) => {
	const rows = groupUsage(reportType, usage);

	expect(rows[0]?.period).toBe(expectedPeriod);
});

Narrowing with assert:

it('returns the first row', () => {
	const rows = getRows();
	const firstRow = rows[0];
	assert.isDefined(firstRow, 'expected at least one row');

	expect(firstRow.id).toBe('row-1');
});