Tutorial

Installing library

We use the library documentationtesting which provides what we need to get started. For a complete description of how to use it go to the documentation site

The library is not yet on a public repository. To use it, you need to download and install it.

You have to download .jar and .pom from last Documentation Testing release

Run this maven command to install it:

mvn install:install-file -Dfile=<path-to-file>.jar -DpomFile=<path-to-pomfile>.pom

Then, you can add the dependency to your pom.xml to use it in your project

<dependency>
    <groupId>org.sfvl</groupId>
    <artifactId>documentationtesting</artifactId>
    <version>${documentationtesting.version}</version>
    <scope>test</scope>
</dependency>

Configuration

In your pom.xml add the dependency to the library

<dependency>
   <groupId>org.sfvl</groupId>
   <artifactId>documentationtesting</artifactId>
   <version>[DOCUMENTATIONTESTING VERSION]</version>
   <scope>test</scope>
</dependency>

Replace [DOCUMENTATIONTESTING VERSION] with the installed version number.

Create a test

Create a simple test class in your test directory src/test/java. Register the extension adding those lines

@RegisterExtension
static ApprovalsExtension doc = new SimpleApprovalsExtension();

Create a test method and use doc.write() to write every thing you want to view in documentation and have to be validate

@Test
public void my_first_test() {
    String text = "hello";
    doc.write(String.format("\"%s\".toUpperCase() => \"%s\"",
            text,
            text.toUpperCase()));
}

Execution

Run the test as usual with your IDE or using the command mvn test. The first execution will fail and files with extension .received.adoc will be generate in src/test/doc, one file per test class ([MY CLASS].received.adoc) and one file per test ([MY CLASS].[MY METHOD].received.adoc).

Rename all files replacing .received.adoc by .approved.adoc. Relaunch your test and it will pass.

With the test described in 'Create a test' chapter, this _[MY CLASS].my_first_test.approved.adoc file contains:

= My first test

"hello".toUpperCase() => "HELLO"

Convert to HTML

You can see the .adoc file directly in a browser or with your IDE after installing a asciidoc viewer. But you may want to have an HTML file.

Add this configuration to your pom.xml.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.1.0</version>
    <configuration>
        <sourceDirectory>src/test/docs</sourceDirectory>
        <outputDirectory>docs</outputDirectory>
        <preserveDirectories>true</preserveDirectories>
        <relativeBaseDir>true</relativeBaseDir>
        <backend>html</backend>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Create a file index.adoc at the root of the docs folder.

= Documentation

include::[FOLDER]/_[MY CLASS].approved.adoc[leveloffset=+1]

[FOLDER] is the path from src/test/docs folder to the .adoc file. It’s the path corresponding to the package of the class.

Run the Maven command:

mvn package

You will find an index.html in the folder docs at the root of your project folder.

Doc as test