test-assertions

Strict Test Assertions

Write each assertion to capture a value's complete structure in one strict deep-equality check. Reach for one full-value assertion first rather than a cluster of narrow checks you consolidate later. Hold existing tests to the same standard when reviewing or strengthening them.

Select the scope

• Use the file or directory named by the user when provided.
• Otherwise, use test files in staged and unstaged changes when the working tree contains changes.
• Otherwise, use all test files in the repository.

Do not change snapshots unless the user explicitly includes them.

Prefer the strongest assertion

Use the strictest deep-equality matcher the framework offers for objects, arrays, sets, maps, class instances, and other structured values (in Jest, toStrictEqual). Replace looser equality, partial matchers, property checks, containment checks, length checks, and existence guards when one complete assertion can express the expected value.

Use exact-equality for primitives (in Jest, toBe). Tighten calls and exceptions to their exact observable contract: the exact arguments, error type, and message.

Assert native collection types directly rather than converting them to arrays.

Discover expected values from the test

Do not infer an expected value from implementation code. When writing a new assertion or replacing a weak one, start with a deliberately incomplete strict assertion, run the narrowest relevant test, and use the failure output to capture the actual value. Then review that value as the intended contract and rerun the test.

expect(result).toStrictEqual({});

If the observed value reveals a bug or an unclear contract, stop and ask the user instead of blessing it as expected behavior.

Assert the whole value at once

Write one structural assertion instead of several narrow ones; collapse fragmented assertions in existing tests the same way:

expect(result).toStrictEqual({
	id: 'order-100',
	status: 'confirmed',
	items: [
		{sku: 'A-100', quantity: 2},
		{sku: 'B-100', quantity: 1},
	],
	shipping: {method: 'express', estimatedDays: 3},
});