unit-tests

Jest Testing Best Practices

This guide covers testing patterns and best practices for Jest and React Testing Library in the Wonder Blocks codebase.

Core Testing Principles

⚠️ Critical Setup Rules

Test Workflow Priority:

• ✅ ALWAYS fix failing tests BEFORE fixing linting errors
• ✅ Focus on underlying errors, not Unhandled console.error call messages
• ⚠️ When tests fail with Unhandled console.error call, look for the root cause error (e.g., ReferenceError: window is not defined)
• ⚠️ The console.error messages are symptoms, not the actual problem - fix the underlying issue

File Structure:

• ✅ Name test files with .test.ts or .test.tsx suffix
• ✅ Place in __tests__/ directory OR colocate with source files (follow local conventions)

Test Framework Setup:

• ✅ Additional matchers from React Testing Library (RTL) and jest-extended are available
• ✅ Use describe/it pattern for test organization
• ✅ Use globalThis prefix when accessing global objects
• ✅ Prioritize testing non-trivial business logic over trivial implementations

Arrange-Act-Assert Pattern

⚠️ ALWAYS use this three-section structure:

describe("Calculator", () => {
    it("should add two numbers correctly", () => {
        // Arrange
        const a = 5;
        const b = 3;

        // Act
        const result = add(a, b);

        // Assert
        expect(result).toBe(8);
    });
});

Rules:

• ✅ ALWAYS divide tests into Arrange, Act, Assert sections with comments
• ✅ Each section gets exactly one comment label (// Arrange, // Act, // Assert) — no additional comments within a section
• ❌ NEVER combine sections (e.g., don't write // Act & Assert)
• ❌ NEVER use multiple Act or Assert sections in a single test (split into separate tests instead)
• ❌ NEVER remove Arrange, Act, Assert comments

Exception - Testing Thrown Errors:

When testing errors, use an underTest variable in the Act section: