unit-testing

Unit Testing

Structured guidance for writing reliable, maintainable unit tests — covering test anatomy, mocking strategies, parameterized tests, TDD workflow, coverage strategy, and test organization across Python, TypeScript, and Go.

When to Activate

• Writing tests for a function, class, or module
• Setting up a test framework for a new project
• Mocking or stubbing external dependencies in tests
• Deciding what to unit test vs integration test
• Practising TDD (test-driven development) on a new feature
• Achieving or enforcing a coverage target
• Debugging a flaky or unclear test failure

---

Test Anatomy

Arrange / Act / Assert (AAA)

Every test has three distinct phases:

• Arrange — set up the inputs, dependencies, and state needed for the test
• Act — call the unit under test (exactly once)
• Assert — verify the outcome matches expectations

One assertion per logical concern means each test validates one observable behaviour. Multiple assert statements are fine as long as they all verify the same thing (e.g., both fields of a returned object).

Test Naming

Language	Convention	Example
Python	test_<unit>_<scenario>_<expected_result>	test_divide_by_zero_raises_value_error
TypeScript	describe('Unit') / it('should ...')	it('should throw when dividing by zero')
Go	TestXxx with t.Run("SubtestName", ...)	TestDivide/ByZero

Well-Structured Test Examples

# Python — pytest
def test_calculate_total_with_discount_returns_reduced_price():
    # Arrange
    cart = Cart(items=[Item(price=100)])
    discount = PercentageDiscount(rate=0.10)

    # Act
    total = calculate_total(cart, discount)

    # Assert
    assert total == 90.0

// TypeScript — Jest / Vitest
describe('calculateTotal', () => {
  it('should return reduced price when discount is applied', () => {
    // Arrange
    const cart = { items: [{ price: 100 }] };
    const discount = { rate: 0.10 };

    // Act
    const total = calculateTotal(cart, discount);

    // Assert
    expect(total).toBe(90.0);
  });
});