Testing Antora sites

This project provides utilities and guidelines for testing Antora documentation sites.

Quarkiverse projects usually host their Antora documentation in a dedicated docs Maven module. After adding the quarkus-antora dependency, you can not only life-edit the site in Quarkus dev mode but also

  • Test that Antora is able to generate the site from your AsciiDoc sources

  • Ensure that all external links are valid.

Basic @QuarkusTest

The way we test the site generation is not much different from testing any other Quarkus application.

First, you need to add the necessary dependencies

        <dependency>
            <groupId>io.quarkiverse.antora</groupId>
            <artifactId>quarkus-antora</artifactId>
        </dependency>

        <!-- Test dependencies -->
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-junit5</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.assertj</groupId>
            <artifactId>assertj-core</artifactId>
            <scope>test</scope>
        </dependency>

Then you can add a basic @QuarkusTest as follows:

import org.hamcrest.CoreMatchers;
import org.junit.jupiter.api.Test;

import io.quarkiverse.antorassured.AntorAssured;
import io.quarkus.test.junit.QuarkusTest;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;

@QuarkusTest /* the @QuarkusTest annotation lets Quarkus build and start the Antora site on http://localhost:8081/ */
public class AntoraSiteTest {

    @Test
    public void getIndex() {

        /*
         * If the site was built successfully,
         * we can get the index page and check that
         * it contains some expected content
         */
        RestAssured
                .given()
                .contentType(ContentType.HTML)
                .get("/quarkus-antora/dev/index.html")
                .then()
                .statusCode(200)
                .body(CoreMatchers.containsString("<h1 class=\"page\">Quarkus Antora</h1>"));
    }
    ...
}

The sample code snippets used in this section come from the docs module of Quarkus Antora

Detect dead links with AntorAssured

Antora takes care for validating internal cross-references but it does not help much with ensuring that external links point to existing resources. Page fragments (the part starting with # in page.html#anchor) are not validated by Antora too.

That’s where the io.quarkiverse.antorassured.AntorAssured class provided by Quarkus Antora may come in handy.

To use it, you need to add the following dependency:

        <dependency>
            <groupId>io.quarkiverse.antora</groupId>
            <artifactId>quarkus-antorassured</artifactId>
            <scope>test</scope>
        </dependency>

Then you can use it in a test as follows:

    @Test
    public void validateLinks() {

        AntorAssured
                .links()
                .excludeResolved(
                        /* Broken links available in test-page.adoc for the sake of testing */
                        "https://salkjasjhashgajhhsahgahjas.com",
                        "https://quarkus.io/fake-page",
                        "https://quarkus.io/guides/building-native-image#fake-fragment",
                        /* When running this test, the port is 8081, so the following link is not expected to work */
                        "http://localhost:8080/quarkus-antora/dev/index.html")
                .excludeEditThisPage()
                .validate()
                .assertValid();
    }

In the test, we instruct the link validator to ignore some remote URIs, that we intentionally placed into test-page.adoc for the sake of testing AntoraAssured itself.

If you would like to see the dead link detection in action, just remove the whole excludeResolved(…​) method invocation. After that, you should see the test fail with a report like the following:

[ERROR]   AntoraSiteTest.validateLinks:48
 - /home/user/projects/quarkus-antora/docs/modules/ROOT/pages/index.adoc:59
     - http://localhost:8080/quarkus-antora/dev/index.html -> http://localhost:8080/quarkus-antora/dev/index.html
         - Unable to connect: Connection refused
 - /home/user/projects/quarkus-antora/docs/modules/ROOT/pages/test-page.adoc:15
     - https://quarkus.io/fake-page -> https://quarkus.io/fake-page
         - 404
 - /home/user/projects/quarkus-antora/docs/modules/ROOT/pages/test-page.adoc:14
     - https://salkjasjhashgajhhsahgahjas.com -> https://salkjasjhashgajhhsahgahjas.com
         - Unknown host salkjasjhashgajhhsahgahjas.com
 - /home/user/projects/quarkus-antora/docs/modules/ROOT/pages/test-page.adoc:16
     - https://quarkus.io/guides/building-native-image#fake-fragment -> https://quarkus.io/guides/building-native-image#fake-fragment
         - Could not find #fake-fragment