/testing-best-practices

Meaningful Assertion Messages

Impact: HIGH (debugging speed and CI/CD clarity)

Add descriptive messages to assertions to clarify intent and improve debugging. Messages are especially valuable for complex assertions, numeric comparisons with business meaning, loop-based assertions, and any case where the failure reason is not obvious.

Incorrect

// ❌ Bad: No messages — unclear what failed when tests break
describe('PaymentProcessor', () => {
  test('processes valid payment', async () => {
    const result = await processor.processPayment({
      amount: 100,
      currency: 'USD',
      cardNumber: '4111111111111111'
    });

    expect(result.status).toBe('success');
    expect(result.transactionId).toBeDefined();
    expect(result.amount).toBe(100);
    expect(result.fee).toBeLessThan(5);
  });

  test('validates payment data', () => {
    const errors = validator.validate({
      amount: -50,
      currency: 'INVALID',
      cardNumber: '1234'
    });

    expect(errors.length).toBe(3);
    expect(errors[0].field).toBe('amount');
    expect(errors[1].field).toBe('currency');
    expect(errors[2].field).toBe('cardNumber');
  });

  test('handles currency conversion', () => {
    const result = converter.convert(100, 'USD', 'EUR');

    // When this fails, what was the actual value?
    expect(result).toBeGreaterThan(80);
    expect(result).toBeLessThan(120);
  });
});

Problems:

• When a test fails, the error output gives no context about what was expected
• Numeric comparisons do not explain the business reasoning behind thresholds
• Loop-based assertions do not indicate which iteration failed
• Build logs show cryptic comparisons instead of meaningful failure descriptions

Correct

// ✅ Good: Descriptive messages explain intent and help debugging
describe('PaymentProcessor', () => {
  test('processes valid payment', async () => {
    const result = await processor.processPayment({
      amount: 100,
      currency: 'USD',
      cardNumber: '4111111111111111'
    });

    expect(result.status).toBe('success');
    expect(result.transactionId).toBeDefined();
    expect(result.amount).toBe(100);

    expect(result.fee).toBeLessThan(
      5,
      `Processing fee ${result.fee} exceeds maximum allowed fee of 5`
    );
  });

  test('validates payment data', () => {
    const errors = validator.validate({
      amount: -50,
      currency: 'INVALID',
      cardNumber: '1234'
    });

    expect(errors).toHaveLength(3);

    const expectedErrors = [
      { field: 'amount', reason: 'Amount must be positive' },
      { field: 'currency', reason: 'Invalid currency code' },
      { field: 'cardNumber', reason: 'Card number too short' }
    ];

    expectedErrors.forEach(({ field, reason }, index) => {
      expect(errors[index]).toMatchObject(
        { field },
        `Expected error at index ${index} to be for field "${field}" (${reason})`
      );
    });
  });

  test('handles currency conversion within expected range', () => {
    const result = converter.convert(100, 'USD', 'EUR');

    expect(result).toBeGreaterThan(
      80,
      `Converted amount ${result} EUR is below minimum expected (80 EUR for 100 USD)`
    );
    expect(result).toBeLessThan(
      120,
      `Converted amount ${result} EUR exceeds maximum expected (120 EUR for 100 USD)`
    );
  });
});

// Using custom matchers for domain-specific assertions
expect.extend({
  toBeWithinRange(received: number, floor: number, ceiling: number) {
    const pass = received >= floor && received <= ceiling;

    return {
      pass,
      message: () =>
        pass
          ? `Expected ${received} not to be within range ${floor} - ${ceiling}`
          : `Expected ${received} to be within range ${floor} - ${ceiling}, but it was ${
              received < floor ? `${floor - received} below minimum` : `${received - ceiling} above maximum`
            }`
    };
  }
});

describe('with custom matchers', () => {
  test('conversion rate within expected range', () => {
    const result = converter.convert(100, 'USD', 'EUR');
    expect(result).toBeWithinRange(80, 120);
  });
});

Benefits:

• Faster debugging because failure messages immediately explain what went wrong
• Context is preserved in the error output showing actual values involved
• Messages document the business reasoning behind assertions
• CI/CD build logs show meaningful failures instead of cryptic comparisons
• Reviewers understand the intent of assertions without reading surrounding code

Reference: Jest Docs — Expect