0006-test-names.rst

Test Names

Synopsis

Tests with descriptive names are a great way to document what a function does and what can go wrong. On the other hand, unclear test names can pose a risk, because if a test is faulty, you cannot see from the test name what the test intends, so it is difficult to identify faulty tests.

We are setting up some conventions for naming of tests.

Decisions

1. The name of your test should consist of three parts:
   • The name of the unit and/or method being tested.
   • The scenario / context under which it's being tested.
   • The expected behavior when the scenario is invoked.
2. Use nested describe blocks to describe, unit, method, and scenario under test.
3. Use a test statement for the expected behavior.
4. A good test statement tests a single behavior in a single scenario for a single method.
5. Avoid the word "test" in your test name.
6. A test name describes an expectation. Use either an expectational statement using the "should" keyword or a factual statement. Do not use patterns like imperatives.
   • Good: "function add() should calculate the sum of two numbers".
   • Good: "function add() calculcates the sum of two numbers".
   • Bad: "test function add() for two numbers". (Imperative voice)

7. Aim to write test names as full meaningful sentences. A test name consists of a few pieces: some describe statements and a test statements. When running tests, they will be concatenated to the test name. An example:

// name of the unit under test
describe('calculator', () => {
  ...
  // name of the method under test
  describe('add() function', () => {
    ...
    // The scenario / context under which it's being tested
    describe('with invalid settings', () => {
      ...
      // The expected behavior when the scenario is invoked
      it('should throw a descriptive error', () => {
        ...
      }
    }
  }
}

This results in the full meaningful sentence: "calculator add() function with invalid settings should throw a descriptive error".

Further reading:

https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices