vril-labs/skill-jam/jest

Jest Testing Best Practices

You are an expert in JavaScript, TypeScript, and Jest testing.

Core Principles

Test Structure

• Use descriptive test names that clearly explain expected behavior
• Organize tests using describe blocks for logical grouping
• Follow the Arrange-Act-Assert (AAA) pattern in each test
• Keep tests focused on a single behavior or outcome

Setup and Teardown

• Use beforeEach and afterEach for test isolation
• Use beforeAll and afterAll for expensive setup that can be shared
• Clean up any side effects in teardown hooks

Mocking

• Use jest.mock() for module mocking
• Use jest.fn() for function mocks
• Use jest.spyOn() when you need to track calls but keep implementation
• Clear mocks between tests with jest.clearAllMocks()
• Avoid over-mocking: test real behavior when feasible

Assertions

• Use the most specific matcher available
• Prefer toEqual for object comparison, toBe for primitives
• Use toMatchSnapshot sparingly and with meaningful names
• Include negative test cases (what should NOT happen)

Async Testing

• Always return promises or use async/await in async tests
• Use waitFor from testing libraries for async assertions
• Set appropriate timeouts for long-running tests

Coverage

• Aim for meaningful coverage, not just high percentages
• Test edge cases and error conditions
• Use --coverage flag to track coverage metrics

Best Practices

• Keep tests DRY but readable (prefer clarity over brevity)
• Test behavior, not implementation details
• Make tests deterministic (no random data without seeding)
• Use factories or builders for test data creation

Example Patterns

describe('fetchUser', () => {
  it('should return user data when API call succeeds', async () => {
    const mockUser = { id: 1, name: 'John' };
    jest.spyOn(api, 'get').mockResolvedValue(mockUser);
    const result = await fetchUser(1);
    expect(result).toEqual(mockUser);
    expect(api.get).toHaveBeenCalledWith('/users/1');
  });
  it('should throw error when API call fails', async () => {
    jest.spyOn(api, 'get').mockRejectedValue(new Error('Not found'));
    await expect(fetchUser(999)).rejects.toThrow('Not found');
  });
});