Guidelines for writing and reviewing unit tests. Covers AAA pattern, test naming, determinism, mocking strategies, and reviewer responsibilities. Use when creating or updating *.test.* files, reviewing test PRs, or refactoring tests to improve clarity and coverage.
Best practices for writing and reviewing unit tests. Contains rules covering test structure, naming, determinism, and code review.
Reference: MetaMask Unit Testing Guidelines
Reference these guidelines when:
| Priority | Category | Impact | Rule File |
|---|---|---|---|
| 1 | Best Practices | CRITICAL |
rules/best-practices.md |
| 2 | Determinism | HIGH | rules/determinism.md |
| 3 | Reviewer Guide | MEDIUM | rules/reviewer-guide.md |
| 4 | Anti-patterns | MEDIUM | rules/anti-patterns.md |
Use the AAA pattern (Arrange, Act, Assert):
it('indicates expired milk when past due date', () => {
// Arrange
const today = new Date('2025-06-01');
const milk = { expiration: new Date('2025-05-30') };
// Act
const result = isMilkGood(today, milk);
// Assert
expect(result).toBe(false);
});
Meaningful test names - describe purpose, not implementation:
it('displays an error when input is invalid', () => { ... });
One behavior per test, isolated from others.
See rules/best-practices.md for complete guidance.
Mock time, randomness, and external systems:
jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01'));
See rules/determinism.md for details.
Test the test - validate tests fail when code is broken:
// Break the SuT and make sure this test fails
expect(result).toBe(false);
toBeOnTheScreen vs toBeDefined)See rules/reviewer-guide.md for details.
Avoid:
toBeDefined, toBeTruthy) for element presenceSee rules/anti-patterns.md for examples.
yarn test:unitBefore submitting a PR with tests:
*TestUtils/*TestFactory classes before creating new fixtures