wonder-blocks unit-tests.instructions.md

Wonder Blocks - 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)

File Structure:

• Name test files with .test.ts or .test.tsx suffix
• Place in __tests__/ directory OR colocate with source files

Test Framework Setup:

• Additional matchers from 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
• Always use separate comments for each section
• Never combine sections (don't write // Act & Assert)
• Never use multiple Act or Assert sections in a single test
• Never remove Arrange, Act, Assert comments

Exception - Testing Thrown Errors:

it("should throw an error when input is invalid", () => {
    // Arrange
    const invalidInput = "invalid";

    // Act
    const underTest = () => {
        processInput(invalidInput);
    };

    // Assert
    expect(underTest).toThrow("Invalid input");
});

What to Test

DO Test:

• Non-trivial business logic - Complex calculations, data transformations, validation
• User interactions - Click handlers, form submissions, keyboard navigation
• Accessibility - ARIA attributes, keyboard support, focus management
• Edge cases and error conditions - Null values, empty states, error handling
• Integration points - API calls, event callbacks, state changes
• Bug fixes - Add tests that reproduce bugs to prevent regressions