test-assertions

Strict Test Assertions

Capture a value's complete structure in one strict deep-equality check instead of a cluster of narrow checks. When rewriting existing tests, rethink each test as a whole rather than tweaking individual lines, and collapse weak assertions about the same value into one strict check against the complete expected value.

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 snapshot assertions (toMatchSnapshot) unless the user explicitly includes them.

Prefer the strongest assertion

Use the strictest deep-equality matcher the framework offers for structured values (in Jest, toStrictEqual). Ranked from worst to best, in Jest and Chai terms; only the last is good enough:

• toBeTruthy, toBeDefined, not.toBeNull: barely checks anything
• toHaveProperty('key'): only checks existence, not value
• toContain, toMatch: substring/regex match hides the full value
• toHaveLength(n): only checks count, not contents
• toMatchObject, objectContaining, arrayContaining: allows extra properties to sneak in
• toEqual, to.deep.equal: close, but ignores class mismatches and undefined vs missing
• toStrictEqual: the only acceptable assertion for objects and arrays

Migrate existing toEqual and to.deep.equal assertions to toStrictEqual too. Use exact equality for primitives (in Jest, toBe is fine for strings, numbers, booleans, null). Tighten calls and exceptions to their exact observable contract: the exact arguments, error type, and message.

• toThrow() or toThrow(/partial/) → toThrow(new SpecificError("exact message"))
• toHaveBeenCalled() → toHaveBeenCalledWith("exact", "args")

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 to confirm it passes.