Generate an asciidoc file

We want an output document that looks like:

Should add 2 numbers

2 + 3 = 5

You can do it with a simple Asciidoc file like this one:

= Should add 2 numbers

2 + 3 = *5*

To generate this kind of file, that is just a text file, you can do it with this simple code below.

@Test
public void should_add_2_numbers() throws IOException {
    final Path filePath = docPath.resolve("_DemoTest.adoc");
    final FileWriter fileWriter = new FileWriter(filePath.toFile().toString());
    try (BufferedWriter writer = new BufferedWriter(fileWriter)) {

        int a = 2;
        int b = 3;

        final String output = String.join("\n",
                "= Should add 2 numbers",
                "",
                String.format("%d + %d = *%d*", a, b, a + b));

        writer.write(output);
    }
}

Check non regression with source control

To check there is no regression, put the generated file under source control and verify that it was not modified between two executions.

With git, you can use the following command to see all files modified and not yet staged.

git status -s --no-renames [DOC FOLDER]

When you add modified files to the staged using git add, they no longer appear with the command above even they are not committed. You can consider that adding them is a kind of validation.

Check regression with Approvals

If you want to automate that the file has not changed from the last approved file, you can use Approvals with the following code. First time, test failed because there is no approved file. Once you approved the file, the test passes until the output changes.

/**
 * Demo of a simple usage to generate documentation and validate it with https://github.com/approvals[Approvals].
 */
public class DemoWithApprovalsTest {

    /**
     * When adding two simple numbers, the java operator '+' should return the sum of them.
     */
    @Test
    public void should_add_2_numbers() {
        int a = 2;
        int b = 3;
        int result = a + b;

        final String output = String.join("\n",
                "= Should add 2 numbers",
                "",
                String.format("%d + %d = *%d*", a, b, result));

        Approvals.verify(output);
    }
}

Use DocumentationTesting

You can also use DocumentationTesting tool that integrate Approvals , format file name, add comment description and add some commodities.

/**
 * Demo of a simple usage to generate documentation and validate it with https://sfauvel.github.io/documentationtesting/documentationtesting/[Documentation testing].
 */
public class DemoWithDocumentationTestingTest {

    @RegisterExtension
    static ApprovalsExtension doc = new SimpleApprovalsExtension();

    /**
     * When adding two simple numbers, the java operator '+' should return the sum of them.
     */
    @Test
    public void should_add_2_numbers() {
        int a = 2;
        int b = 3;
        int result = a + b;

        final String output = String.format("%d + %d = *%d*", a, b, result);

        doc.write(output);
    }
}

The final file look likes:

Demo with documentation testing test

Demo of a simple usage to generate documentation and validate it with Documentation testing.

Should add 2 numbers

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

2 + 3 = 5

Sources

Sources of thoses samples: https://github.com/sfauvel/documentationtesting/tree/master/samples/demo_minimal