HSC Gradle Plugin

org.aim42 org.aim42.htmlSanityCheck.gradle

The Gradle plugin of HTML Sanity Check (HSC) enables to check generated or native HTML documentation from the Gradle build.

Installation (Gradle Plugin)

Default Installation

Use the following snippet inside a Gradle build file:

build.gradle
plugins {
    id 'org.aim42.htmlSanityCheck' version '2.0.0-rc1' (1)
}
1 Checkout current version

Legacy Installation

In the case of legacy plugin usage

build.gradle
buildscript {
    repositories {
        // maven { url "https://jitpack.io/" } (1)
        mavenCentral() (2)
        gradlePluginPortal() (3)
    }

    dependencies {
        classpath ('gradle.plugin.org.aim42:htmlSanityCheck:2.0.0-rc1') (4)
    }
}

apply plugin: 'org.aim42.htmlSanityCheck'
1 In case you would like to use a development version (or even branch), check out development versions.
2 Beginning with version 2.x all releases will be published to Maven Central.
3 The Gradle Plugin Portal contains most versions or will redirect downloads of newer versions to Maven Central.
4 Check out the current version.
Latest (development) versions

Usage

The plugin adds a new task named htmlSanityCheck.

This task exposes a few properties as part of its configuration:

sourceDir (mandatory)

Directory where the HTML files are located.

Type: Directory.

sourceDocuments (optional)

An override to process several source files, which may be a subset of all files available in {sourceDir}.

Type: org.gradle.api.file.FileCollection.

Default: All files in {sourceDir} whose names end with .html.

checkingResultsDir (optional)

Directory where the checking results written to.

Type: Directory.

Default: +{buildDir}+/reports/htmlSanityCheck/

junitResultsDir (optional)

Directory where the results are written to in JUnit XML format. JUnit XML can be read by many tools, including CI environments.

Type: Directory.

Default: +{buildDir}+/test-results/htmlchecks/

failOnErrors (optional)

Fail the build if any error was found in the checked pages.

Type: Boolean.

Default: false.

httpConnectionTimeout (optional)

Timeout for http requests in ms.

Type: Integer.

Default: 5000.

ignoreLocalHost (optional)

Ignore localhost as hostname.

Type: Boolean.

Default: false.

ignoreIPAddresses (optional)

Ignore IP addresses as hostname.

Type: Boolean.

Default: false.

checkerClasses (optional)

The set of checker classes to be executed.

Type: List.

Default: All available checker classes.

Checker Classes
// Keep the list ordering to ensure
// report ordering comparability
// with HSC 1.x versions
MissingAltInImageTagsChecker.class,
MissingImageFilesChecker.class,
DuplicateIdChecker.class,
BrokenHttpLinksChecker.class,
ImageMapChecker.class,
BrokenCrossReferencesChecker.class,
MissingLocalResourcesChecker.class
httpWarningCodes (optional)

Additional HTTP response codes treated as warning.

Type: List.

Default:

100, 101, 102
// Redirects included
301, 302, 303, 307, 308
HTTP Redirects

Note that HTTP redirects are treated as a warning to make the user aware of the correct or new location (cf. Issue 244). Some HSC reports often contain the respective location.

httpErrorCodes (optional)

Additional HTTP response codes treated as error.

Type: List.

Default:

400, 401, 402, 403, 404,
405, 406, 407, 408, 409,
410, 411, 412, 413, 414,
415, 416, 417, 418, 421,
422, 423, 424, 425, 426,
428, 429, 431, 451,
500, 501, 502, 503, 504,
505, 506, 507, 508, 510,
511
httpSuccessCodes (optional)

Additional HTTP response codes treated as success.

Type: List.

Default:

200, 201, 202, 203, 204,
205, 206, 207, 208, 226
HTTP response code handling

The lists shown above are the default HTTP response codes handled by HSC. The mentioned configurations effectively move the configured codes around, i.e., if you add 308 to httpErrorCodes it is automatically removed from its default list (httpWarningCodes).

Examples

Small Example

build.gradle

apply plugin: 'org.aim42.htmlSanityCheck'

htmlSanityCheck {
    sourceDir = file( "$buildDir/docs" )

    // where to put results of sanityChecks...
    checkingResultsDir = file( "$buildDir/report/htmlchecks" )

    // fail build on errors?
    failOnErrors = true

}

Extended example

build.gradle
import org.aim42.htmlsanitycheck.check.*

buildscript {
    repositories {
        mavenCentral()
        // This is only necessary for older releases (< 2.00)
        gradlePluginPortal()
    }
}

plugins {
    id 'org.aim42.htmlsanitycheck' version '2.0.0-rc1'
    id 'org.asciidoctor.convert' version '1.5.8'
}

// ==== path definitions =====
// ===========================

// location of AsciiDoc files
def asciidocSrcPath = "$projectDir/src/asciidoc"

// location of images used in AsciiDoc documentation
def srcImagesPath = "$asciidocSrcPath/images"

// results of asciidoc compilation (HTML)
// (input for htmlSanityCheck)
// this is the default path for asciidoc-gradle-convert
def htmlOutputPath = "$buildDir/asciidoc/html5"

// images used by generated html
def targetImagesPath =   htmlOutputPath + "/images"

// where HTMLSanityCheck checking results ares stored
def checkingResultsPath = "$buildDir/report/htmlchecks"


apply plugin: 'org.asciidoctor.convert'

asciidoctor {
    sourceDir = new File( asciidocSrcPath )

    options backends: ['html5'],
            doctype: 'book',
            icons: 'font',
            sectlink: true,
            sectanchors: true

    resources {
        from( srcImagesPath )
        into targetImagesPath
    }


}

apply plugin: 'org.aim42.htmlSanityCheck'

htmlSanityCheck {
    // ensure asciidoctor->html runs first
    // and images are copied to build directory

    dependsOn asciidoctor

    sourceDir = new File( htmlOutputPath )

    // files to check, specified as a file tree with filtering
    sourceDocuments = fileTree(sourceDir) {
        include "many-errors.html", "no-errors.html"
    }

    // where to put results of sanityChecks...
    checkingResultsDir = new File( checkingResultsPath )

    // fail build on errors
    failOnErrors = true

   // http connection timeout in milliseconds
    httpConnectionTimeout = 1000

    // which statuscodes shall be interpreted as warning, error or success
    // defaults to standard
    httpWarningCodes = [401]
    // httpErrorCodes
    // httpSuccessCodes

    // only execute a subset of all available checks
    // available checker:
    //   * BrokenCrossReferencesChecker
    //   * BrokenHttpLinksChecker
    //   * DuplicateIdChecker
    //   * ImageMapChecker
    //   * MissingAltInImageTagsChecker
    //   * MissingImageFilesChecker
    //   * MissingLocalResourcesChecker
    checkerClasses = [DuplicateIdChecker, MissingImageFilesChecker]

}

Compatibility

The Plugin has been tested with the following Gradle versions:

Tested Gradle versions
// Test execution in CI will execute all versions.
// Local test is restricted to latest version
// 6.x or older does not work!
'7.6.3', // latest 7.x
'8.0.2', '8.1.1', '8.2.1', '8.3', '8.4',
'8.5', '8.6', '8.7', '8.8', '8.9',
'8.10.1' // all 8.x minor versions (latest patch release)

The full range of Gradle versions is only tested in CI (GitHub action). The local test only tests the latest Gradle version:

Restricting versions to the latest versions locally
def result = System.getenv("GITHUB_ACTION") ? versions : [versions[-1]]

Development versions

In case you want to use a current development (or arbitrary branch or tag) version from GitHub, add the following to your settings.gradle:

settings.gradle
pluginManagement {
    repositories {
        maven { url "https://jitpack.io/" }
    }
}

Then you can use a respective version in your build.gradle:

build.gradle
plugins {
    id 'org.aim42.htmlSanityCheck' version 'develop-SNAPSHOT'
}
JitPack builds

Building the desired version for the first time (or after some cache expiry at JitPack), you may experience a timeout.

You can look up the current build state:

jitpack branch screenshot