diff --git a/docs/decisions/0006-test-names.rst b/docs/decisions/0006-test-names.rst new file mode 100644 index 000000000..e079bcab9 --- /dev/null +++ b/docs/decisions/0006-test-names.rst @@ -0,0 +1,57 @@ +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 \ No newline at end of file