HSC CLI Module

The Command Line Interface (CLI) module of HTML Sanity Check (HSC) enables to check generated or native HTML documentation from the command line.

Installation (Command Line Interface)

Prerequisites

  • Java 8 or higher (java executable required on the OS search path (${PATH} on Linux/macOS, `%path% on Windows).

Download

Download the latest version of the HSC CLI from the release page.

Usage

The CLI tool can be executed with the following command. If the sourceDirectory is omitted, HSC uses the current directory as base-directory to search for HTML files.

Linux / macOS
hsc [ options ] [ sourceDirectory ]
Windows
hsc.bat [ options ] [ sourceDirectory ]

Options

The CLI tool exposes a few options as part of its configuration:

<sourceDirectory> (optional)

Directory where the HTML files are located.

Type: Directory

Default: Currrent directory (.)
--sourceDocuments <…​> (optional)

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

Type: List of files

Default: All files in sourceDir whose names end with .html
--checkingResultsDir <…​> (optional)

Directory where HSC writes the checking results.

Type: Directory

Default: ./reports/htmlSanityCheck/
--junitResultsDir <…​> (optional)

Directory where HSC writes the results in JUnit XML format. JUnit XML can be read by many tools, including CI environments.

Type: Directory

Default: ./test-results/htmlchecks/
--failOnErrors (optional)

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

Type: Boolean

Default: false
--httpConnectionTimeout <value> (optional)

Timeout for HTTP requests in milliseconds.

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:

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)

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 contain the respective location.
--httpErrorCodes (optional)

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)

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

Basic Example

java -jar htmlSanityCheck-cli-<version>.jar --sourceDir ./docs

Extended Example

java -jar htmlSanityCheck-cli-<version>.jar \
  --sourceDir ./docs \
  --checkingResultsDir ./report/htmlchecks \
  --failOnErrors true \
  --httpConnectionTimeout 1000 \
  --checkerClasses DuplicateIdChecker,MissingImageFilesChecker

Compatibility

The CLI tool has been tested with the following Java versions:

  • Java 8

  • Java 11

  • Java 17

  • Java 21

Development Versions

In case you want to use a current development (or arbitrary branch or tag) version from GitHub, you can build the CLI tool from source.

Clone the repository
git clone https://github.com/aim42/htmlSanityCheck.git
cd htmlSanityCheck
Build the CLI tool
./gradlew integrationTest

Gradle generates the application to htmlSanityCheck-cli/build/install/hsc/.