Getting started

To get started quickly, you can download Try doc as test project. It’s a minimal project that is ready to use and that implements a small demo.

You can alo follow steps of the Get started page.

You can use it on your own project alongside your existing tests. Both can work together without modifying your tests.

To do that, you need to:

  • Installing DocumentationTesting maven library and add dependency to your pom.xml

  • Create a test and register ApprovalsExtension extension adding the code below to the test class.

@RegisterExtension
static ApprovalsExtension extension = new SimpleApprovalsExtension();

  • Write in your test everything you want to see in your documentation using doc.write("…​") You don’t have to write assertions, tests will be passed when generated documents are the same as the last time.

Creating a test using ApprovalsExtension

This is an example to create a simple test using ApprovalsExtension.

You have to write a class and add register an ApprovalsExtension attribute using RegisterExtension annotation. This extension will check that everything wrote using write method has not changed since the last execution.

Test example using ApprovalsExtension
package com.github.docastest.samples.justone;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;
import com.github.docastest.doctesting.junitextension.ApprovalsExtension;
import com.github.docastest.doctesting.junitextension.SimpleApprovalsExtension;
public class OneTest {
    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

}

When executing test method test_A, the following text is generated.

[#com_github_docastest_samples_justone_onetest_test_a]
= Test A

In my *test*

If this content is identical to the _OneTest.test_A.approved.adoc, then the test is a success. Otherwise, test fails and the generated text is written to the _OneTest.test_A.received.adoc file. So we can compare those two files to see what has changed.

File name and title come from method name. The chapter content contains what was written using write.

Files are stored in src/test/docs/com/github/docastest/samples/justone directory which contains:

  • _OneTest.approved.adoc

  • _OneTest.test_A.approved.adoc

There is one file per test and one file for the class.

Organize documentation

To organize documentation, we have to consider test methods as the generator of one chapter. Each test will have a title by default following by text added executing it. Some of them show a specific behavior like any classic test.

But, it’s also possible to have one test that runs several cases and presents a global report of the execution. Even if there is a regression for one case in that test, all results will be written in the document and can be compared with the reference file.

We also can create a test method that just write text without code execution. It can be used to add general description or to minimize what it is written in a test to simplify its reuse.

The final document respect the order of the method in the test file. We can use subclasses to create subchapter in the document (see: Nested class)

It’s not necessary to follow source code organization in tests. Instead, organize your test packages according to the document you want to generate.

Format text

To format text, we can use a formatter that hide technical syntax of the markup language used.

Formatter usage
Formatter formatter = new AsciidocFormatter();
final String text = formatter.listItems("Item A", "Item B", "Item C");
Text generated
* Item A
* Item B
* Item C
Example 1. Final rendering

  • Item A

  • Item B

  • Item C

You can take a look at the formatter’s full documentation to get an idea of the features available.

Extract code

Even if we often try to document the behavior of the application with as little technical element as possible, we also need to show some code to document how to use it.

To do that, there is tools provided to do this simply. You will find one way to extract code below. If you want a to see all possibilities, go to CodeExtractionPackage

Extract a part of code from method

To extract a part of a method, you can write a comment with a specific value that indicate beginining of the code to extract. Another comment with a specific value indicate the end of the code.

How to extract part of a method code
Method method = MethodReference.getMethod(ClassWithMethodToExtract::methodWithOnePartToExtract);
String code = CodeExtractor.extractPartOfMethod(method);

or

String code = CodeExtractor.extractPartOfMethod(ClassWithMethodToExtract.class, "methodWithOnePartToExtract");
Source code from file
public void methodWithOnePartToExtract() {
    int i = 0;
    // >>>
    int j = i;
    // <<<
    int k = i + j;
}
Source code extracted
int j = i;

You can have several part identify by a text that you pass as argument to the function extracting the code. You can have several part identified by the same text. In that case, all parts matching the text will be returned.

How to extract part of a method
Method method = MethodReference.getMethod(ClassWithMethodToExtract::methodWithSeveralPartsToExtract);
String codePart1 = CodeExtractor.extractPartOfMethod(method, "Part1");
String codePart2 = CodeExtractor.extractPartOfMethod(method, "Part2");
Source code from file
public int methodWithSeveralPartsToExtract(int value) {
    // >>>Part1
    int square = value * value;
    // <<<Part1

    // >>>Part2
    final String text = String.format(
            "square(%d)=%d",
            value,
            square);
    System.out.println(text);
    // <<<Part2

    // >>>Part1
    return square;
    // <<<Part1
}
Source code Part 1 extracted
int square = value * value;
return square;
Source code Part 2 extracted
final String text = String.format(
        "square(%d)=%d",
        value,
        square);
System.out.println(text);

Generate html

To convert .adoc to .html, we use asciidoctor-maven-plugin plugin. It’s configure in pom.xml and it’s can be run in one phase of the maven lifecycle (generally the package phase).

By default, files started with _ are not converted to HTML by this plugin. We have chosen to start all approved file names with an _. They are only chapters of documents. They need to be included in a file that will be converted into HTML. So, this makes it easier to reuse these chapters and organize the documentation.

To have a file that not start with _, we need to generate one. The HtmlPageExtension extension is made for that. When a test class used this extension, it will generate a simple .adoc file that include the approved file of the same class. The final HTML file will contain all the chapters generated from methods of this class.

Example of class creating the file that will be converted into HTML
@ExtendWith(HtmlPageExtension.class)
public class HtmlTest {
    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

}

Files in folder src/test/docs/com/github/docastest/samples/generateHtml

  • HtmlTest.adoc

  • _HtmlTest.approved.adoc

  • _HtmlTest.test_A.approved.adoc

Content of the file src/test/docs/com/github/docastest/samples/generateHtml/HtmlTest.adoc
include::_HtmlTest.approved.adoc[]

For more features, you can look at the documentation on creating a document.

Use your own style

To have specific style in some chapter, you can use HTML style directly in your Asciidoc files.

You need to encapsulate it between ++++ and <style> balise.

Define a custom style

You can customize style adding a css style directly in your file. You need to put an html style tag (<style></style>) enclosed in ++++ to add it without processed content and send it directly to the output.

Asciidoc content
++++
<style>
.withColor {
   color: blue;
}
</style>
++++
This text should be black.

[.withColor]#This text shoud be blue.#

This text should be black.

[.withColor]
--
This section formed by several lines in asciidoc
should be blue.
--
This text should be black.
Example 2. Content rendering

This text should be black.

This text shoud be blue.

This text should be black.

This section formed by several lines in asciidoc should be blue.

This text should be black.

Visualize data with a graph

It is very common to have to present the values obtained according to the input data. To do this, there is nothing better than to display a graph. We provide a way to do it easily generating a SVG from the data.

Draw several lines

final String svg = new SvgGraph()
        .withLine("Line A", Arrays.asList(-15, 6, 30, 25))
        .withLine("Line B", Arrays.asList(5, 12, 45, 17))
        .withLine("Line C", Arrays.asList(-5, -10, -20, 8))
        .generate();
45 -20 0 3

For more features, you can look at the Create a graph to visualize data.