Quick start

You can experiment it simply with almost nothing.

  1. Use your usual test framework.

  2. Create a test that write to a text file.

  3. Put the result of the test execution in that text.

  4. Add the file to git.

You now have a non regression test in place. Each time you run this test, a change in the file is a regression. You can use git to detect file changes and to see the differences with the previous version.

By the time, you can add useful information to the output file and format it to be more readable.

Java project

DocumentationTesting is a java library which provides tools to easily implement this approach.

Ready to test project

You can use the TryDocAsTest project. It’s a preconfigure project to start with a complete tool.

Use it in your own project

You want to create your own Java project to try this approach. The only module you need is documentationtestesting one.

Start by writing a test that inherits from org.sfvl.doctesting.junitinheritance.ApprovalsBase.

Use write method to write all you want to be in documentation. It should be at least input and output. When you write output, you don’t write values expected but only values given by the application.

Then run test as usual. First time, test fails and a file is produced in src/test/docs with the name of the test. The filename ends with received.adoc.

Read the file and verify that it looks like as you want. If it is the case, rename it with approved.adoc instead of received.adoc.

Relaunch tests and they should pass.

Example with DemoTest.java
package org.sfvl.demo;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.sfvl.doctesting.utils.NoTitle;

/**
 * Demo of a simple usage to generate documentation.
 */
public class DemoTest extends DemoBaseClass {

    @Test
    @NoTitle
    public void note_demo() {
        super.note_demo();
    }

    /**
     * When adding two simple numbers, the java operator '+' should return the sum of them.
     */
    @Test
    @DisplayName("Adding 2 simple numbers")
    public void should_be_5_when_adding_2_and_3() {
        int a = 2;
        int b = 3;
        doc.write(String.format("%d + %d = %d", a, b, a + b));
    }
}

File generated to validate

Adding 2 simple numbers

When adding two simple numbers, the java operator '+' should return the sum of them.

2 + 3 = 5