Documentation Comments on Test Methods

I just want to share a minor inspiration which might help in daily business with unit tests.

Using behaviour driven development, some people like to put all identifying properties into the method name. That can escalate quickly in complex tests.

func testSubjectUnderTest_GIVEN_dependenciesAreSetUp_WHEN_doSomething_THEN_haveFun() {}

This is only a short and simple example. Imagine how that can escalate into a monstrous line of code and how hard it is to parse the contained information while reading. I understood the pattern and agreed with it to some pattern but it does not scale™.

I prefer to keep it rather short than precise and document the details in a more digestible format along the test.

///
/// A quick summary about what this test is about.
///
/// ## Given
///
/// * Everything is set up right.
///
/// ## When
///
/// * Doing something.
///
/// ## Then
///
/// * We expect to have fun.
///
func testDoSomething() {
    // Given
    subjectUnderTest.someDependencyService = dependencyMockObject

    // When
    let result = subjectUnderTest.doSomething()

    // Then
    XCTAssertEqual(result, "Yay!")
}

Much more pleasant and comfortable to read. Okay, I admit that this is overkill for rather simple tests. Of course, adequacy needs to be considered individually. Otherwise dogmatic patterns distract from getting the actual work done. Often enough I do not write tests like this either.