Unit Test

Unit Testing Guidelines

Best practices for writing and reviewing unit tests. Contains rules covering test structure, naming, determinism, and code review.

Reference: MetaMask Unit Testing Guidelines

When to Apply

Reference these guidelines when:

• Writing new unit tests
• Reviewing test code in PRs
• Refactoring existing tests
• Debugging flaky or brittle tests
• Improving test coverage

Rule Categories by Priority

Quick Reference

1. Best Practices (CRITICAL)

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.

2. Determinism (HIGH)

Mock time, randomness, and external systems:

jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01'));

• Avoid relying on global state or hardcoded values
• Only test public behavior, not implementation details

See rules/determinism.md for details.

3. Reviewer Guide (MEDIUM)

Test the test - validate tests fail when code is broken:

// Break the SuT and make sure this test fails
expect(result).toBe(false);

• Ensure proper matchers (toBeOnTheScreen vs toBeDefined)
• Reject complex test names with multiple conditions

See rules/reviewer-guide.md for details.

4. Anti-patterns (MEDIUM)

Avoid:

• Code coverage without real assertions
• Weak matchers (toBeDefined, toBeTruthy) for element presence

See rules/anti-patterns.md for examples.

Workflow

1. Run unit tests after code changes: yarn test:unit
2. Confirm all tests pass before commit

PR Checklist

Before submitting a PR with tests:

• Tests use AAA pattern (Arrange, Act, Assert)
• Test names describe the expected behavior
• One behavior per test
• No reliance on global state or implementation details
• Time/randomness mocked where needed
• Proper matchers used for assertions
• Checked for existing *TestUtils/*TestFactory classes before creating new fixtures
• Extracted shared fixtures to utility class if same setup needed in 2+ test files
• All tests pass locally

Resources

• MetaMask Contributor Docs
• Jest Matchers
• React Native Testing Library

Converted and distributed by TomeVault — claim your Tome and manage your conversions.