Testing Best Practices

When writing unit-tests, always follow the three-A’s: Arrange, Act, Assert. Every test divides into three distinct phases, where each phase has a well-defined role:

• Arrange: set up the test-case, including any inputs, test doubles, and expectations.

• Act: perform the one action under test.

• Assert: check the outcome of the action, including any return values and expected side effects.

Each unit test should verify one specific behavior. Avoid exercising multiple behaviors or features within a single test case.

A unit test must not depend on or alter state that lives outside its own scope. Avoid altering process-global state (e.g. env), modifying globals, mutating singletons, etc.

Instead, design the code to leverage well-defined interfaces that can be tested with test doubles via dependency injection instead, to reduce reliance on global logic.

Write tests against the observable behavior of code, not the way that behavior is implemented; test properties of the functionality instead.

Whenever the only way to derive an expected value is to go read the code you are testing, you are testing the implementation – assert a documented property instead.

Prefer testing the public interface of a unit over its private implementation details. A test should exercise what a unit promises to its callers, not how it achieves it internally.

This style is called black-box testing: the tester knows the external behavior but treats the internal structure as opaque. The helpers still get covered, because the public entry point is what calls them – but nothing in the test breaks when one is renamed, split, or inlined.

Do not write code that detects whether it is running under test and changes its behavior, known as test-aware code. A unit that branches on a test flag, the presence of a test runner, the presence of an environment variable, or a test-only build fundamentally runs a different path under test than it does in production, so the test verifies behavior you do not ship.

Instead, make code testable through design, typically dependency injection, so that tests substitute collaborators without the unit ever knowing.

Name a test after the behavior it verifies: the scenario under test and the expected result. The name is the first thing you see when a test fails, so it should identify the broken behavior without opening the file. A name like test_withdraw_1 or TestAccount forces you to read the body to learn what broke; a name that states the behavior does not.

TEST_CASE("withdraw more than the balance is rejected") {
  // Arrange
  auto account = Account{/*balance=*/100};

  // Act
  const bool ok = account.withdraw(150);

  // Assert
  REQUIRE_FALSE(ok);
  REQUIRE(account.balance() == 100);
}

func TestWithdraw_RejectsAmountAboveBalance(t *testing.T) {
  t.Parallel()

  // Arrange
  account := NewAccount(100)

  // Act
  ok := account.Withdraw(150)

  // Assert
  if got, want := ok, false; got != want {
    t.Errorf("Withdraw(150) = %v, want %v", got, want)
  }
  if got, want := account.Balance(), 100; got != want {
    t.Errorf("Balance() = %d, want %d", got, want)
  }
}

def test_withdraw_more_than_balance_is_rejected():
  # Arrange
  account = Account(balance=100)

  # Act
  ok = account.withdraw(150)

  # Assert
  assert ok is False
  assert account.balance() == 100

#[test]
fn withdraw_more_than_balance_is_rejected() {
  // Arrange
  let mut account = Account::new(100);

  // Act
  let ok = account.withdraw(150);

  // Assert
  assert!(!ok);
  assert_eq!(account.balance(), 100);
}