DOCSEARCHbyAlgolia
Submit Docs

htmltest

repository·master·Indexed 18 days ago

https://github.com/wjdp/htmltest

A fast HTML testing tool written in Go that validates HTML output for broken internal and external links, missing alt tags, valid favicons, and correct DOCTYPE specifications. It serves as a high-performance alternative to Ruby-based tools like html-proofer and can be configured via a .htmltest.yml file or used through a CLI and Docker.

Tokens
4.9K
Snippets
8
Records
14
Agent score
14%

What's inside htmltest

  1. What htmltest checks

    master

    The tool performs several automated checks on your HTML files:

    • Links & Scripts: Validates internal and external links, images, and script references.
    • Internal Hashes: Checks if internal anchor links (#) work.
    • HTTPS: Verifies if external links use HTTPS.
    • Images: Ensures images have valid alt attributes.
    • Favicons: Checks for a valid favicon link.
    • Meta Tags: Validates <meta> refresh tags.
    • DOCTYPE: Verifies that a DOCTYPE is correctly specified.

    Note: htmltest does not currently validate HTML markup well-formedness (e.g., checking if tags are properly closed).

  2. Configure logging and output

    master

    Color Output

    By default, htmltest uses colors in the terminal. To disable this, set the NO_COLOR environment variable.

    Log Files

    Errors are written to tmp/.htmltest/htmltest.log by default. The logging level can be configured via your configuration file.

    Temporary Files and Caching

    htmltest uses tmp/.htmltest for:

    • Logs: Output logs.
    • Cache: A cache of external link status codes (tmp/.htmltest/refcache.json) to speed up subsequent runs. Items expire after two weeks by default.

    It is recommended to ignore tmp/.htmltest in version control, but you may want to cache it in your CI system to improve performance.

  3. Configure htmltest using a YAML file

    master

    htmltest can be configured using a YAML file named .htmltest.yml. Place this file in the directory from which you run the tool. Once configured, you can simply run the htmltest command to execute your tests using these settings.

    It is recommended to cache the tmp/.htmltest directory to improve performance.

    DirectoryPath: "_site"
EnforceHTTPS: true
IgnoreURLs:
- "example.com"
- "^/misc/js/script.js$"
IgnoreDirs:
- "lib"
CacheExpires: "6h"

  4. Install htmltest on Linux or macOS

    master

    You can install htmltest using a godownloader script.

    System-wide Install

    To install the binary into /usr/local/bin (requires sudo):

    curl https://htmltest.wjdp.uk | sudo bash -s -- -b /usr/local/bin

    Local Directory Install

    To install the binary into the ./bin directory of your current folder (useful for CI environments):

    curl https://htmltest.wjdp.uk | bash
    curl https://htmltest.wjdp.uk | sudo bash -s -- -b /usr/local/bin

  5. Ignore specific HTML elements from checks

    master

    To prevent htmltest from checking a specific element, add the data-proofer-ignore attribute to the tag or to the class of the tag. The name of this attribute can be customized in your configuration.

    <a href="http://notareallink" data-proofer-ignore>Not checked.</a>

  7. Run htmltest via Docker

    master

    You can run htmltest using Docker by mounting your directory containing HTML files to the /test path inside the container.

    Basic usage:

    docker run -v $(pwd):/test --rm wjdp/htmltest

    With arguments: To pass arguments to the test run, append them to the end of the command:

    docker run -v $(pwd):/test --rm wjdp/htmltest -l 3 -s
    docker run -v $(pwd):/test --rm wjdp/htmltest

  8. Understand htmltest exit codes and output

    master

    The htmltest CLI communicates results via standard output and exit codes:

    • Success (0): If no errors are found, the tool prints a success message (e.g., ✔✔✔ passed in ...) and exits with code 0.
    • Failure (1): If errors are detected, the tool prints a failure message (e.g., ✘✘✘ failed in ...) and exits with code 1.

    Environment Variables

    • NO_COLOR: If this environment variable is set to any value, all terminal colorization will be disabled (following the no-color.org standard).

  9. Use the htmltest CLI to test HTML files

    master

    htmltest is a command-line tool used to test generated HTML for problems. It can be run by specifying a path to a file or directory, or by using a configuration file.

    Execution Modes

    1. Path Argument: If you provide a <path>, htmltest will test that specific file or directory.
    2. Configuration File: If no path is provided, it attempts to read from a default .htmltest.yml file in the current directory.
    3. Custom Config: You can specify a custom configuration file using the -c or --conf flag.

    CLI Usage Examples

    # Test a specific directory (uses default .htmltest.yml if present)
htmltest ./dist

# Test a specific file
htmltest ./dist/index.html

# Use a custom configuration file
htmltest -c custom-config.yml

# Skip external link checks to speed up execution
htmltest -s

# Set logging level (0-3: debug, info, warning, error)
htmltest -l 1
    # Example commands
htmltest ./path/to/html
htmltest -c config.yml
htmltest -s
htmltest -l 2

  10. Configure htmltest via .htmltest.yml

    master

    htmltest can be configured using a YAML file. If no path is provided via the CLI, the tool looks for a .htmltest.yml file in the current working directory. You can also explicitly point to a configuration file using the -c or --conf flag.

    When a configuration file is used, CLI arguments will override or append to the options defined in the YAML file.

  11. Reference: htmltest configuration options

    master

    The following options are available in the .htmltest.yml configuration file. Note that many check-related options (like CheckAnchors, CheckLinks, etc.) default to true.

    | Option | Description | Default |
| :-----|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :------ |
| `DirectoryPath` | Directory to scan for HTML files. | |
| `DirectoryIndex` | The file to look for when linking to a directory. | `index.html` |
| `FilePath` | Single file to test within `DirectoryPath`, omit to test all. | |
| `FileExtension` | Extension of your HTML documents, includes the dot. If `FilePath` is set we use the extension from that. | `.html` |
| `CheckDoctype` | Enables checking the document type declaration. | `true` |
| `CheckAnchors` | Enables checking `<a…` tags. | `true` |
| `CheckLinks` | Enables checking `<link…` tags. | `true` |
| `CheckImages` | Enables checking `<img…` tags | `true` |
| `CheckScripts` | Enables checking `<script…` tags. | `true` |
| `CheckMeta` | Enables checking `<meta…` tags. | `true` |
| `CheckGeneric` | Enables other tags, see items marked with checkGeneric on the [tags wiki page](https://github.com/wjdp/htmltest/wiki/Tags). | `true` |
| `CheckExternal` | Enables external reference checking; all tag types. | `true` |
| `CheckInternal` | Enables internal reference checking; all tag types. When disabled will prevent internal hash checking unless the reference only contains a hash fragment (`#heading`) and therefore refers to the current page. | `true` |
| `CheckInternalHash` | Enables internal hash/fragment checking. | `true` |
| `CheckMailto` | Enables–albeit quite basic–`mailto:` link checking. | `true` |
| `CheckTel` | Enables–albeit quite basic–`tel:` link checking. | `true` |
| `CheckFavicon` | Enables favicon checking, ensures every page has a favicon set. | `false` |
| `CheckMetaRefresh` | Enables checking meta refresh tags. | `true` |
| `EnforceHTML5` | Fails when the doctype isn't `<!DOCTYPE html>`. | `false` |
| `EnforceHTTPS` | Fails when encountering an `http://` link. Useful to prevent mixed content errors when serving over HTTPS. | `false` |
| `IgnoreURLs` | Array of regexs of URLs to ignore. | empty |
| `IgnoreInternalURLs` | Array of strings of internal URLs to ignore. Exact matches only. ⚠ Likely to be deprecated, use `IgnoreURLs` instead. | empty |
| `IgnoreHTTPS` | Array of regexs of URLs to ignore for `EnforceHTTPS`. These URLs are still tested, unless also present in `IgnoreURLs`. | empty |
| `IgnoreDirs` | Array of regexs of directories to ignore when scanning for HTML files. | empty |
| `IgnoreInternalEmptyHash` | When true prevents raising an error for links with `href="#"`. | `false` |
| `IgnoreEmptyHref` | When true prevents raising an error for links with `href=""`. | `false` |
| `IgnoreCanonicalBrokenLinks` | When true produces a warning, rather than an error, for broken canonical links. When testing a site which isn't live yet or before publishing a new page canonical links will fail. | `true` |
| `IgnoreExternalBrokenLinks` | When true produces a warning, rather than an error, for broken external links. Useful when testing a site having hundreds of external links. | `false` |
| `IgnoreAltMissing` | Turns off image alt attribute checking. | `false` |
| `IgnoreAltEmpty` | Allows `alt=""` for decorative images. | `false` |
| `IgnoreDirectoryMissingTrailingSlash` | Turns off errors for links to directories without a trailing slash. | `false` |
| `IgnoreSSLVerify` | Turns off x509 errors for self-signed certificates. | `false` |
| `IgnoreTagAttribute` | Specify the ignore attribute. All tags with this attribute or with this class will be excluded from every check. | `"data-proofer-ignore"` |
| `HTTPHeaders` | Dictionary of headers to include in external requests | `{"Range":  "bytes=0-0", "Accept": "*/*"}` |
| `TestFilesConcurrently` | :warning: :construction: *EXPERIMENTAL* Turns on [concurrent](https://github.com/wjdp/htmltest/wiki/Concurrency) checking of files. | `false` |
| `DocumentConcurrencyLimit` | Maximum number of documents to process at once. | `128` |
| `HTTPConcurrencyLimit` | Maximum number of open HTTP connections. If you raise this number ensure the `ExternalTimeout` is suitably raised. | `16` |
| `LogLevel` | Logging level, 0-3: debug, info, warning, error. | `2` |
| `LogSort` | How to sort/present issues. Can be `seq` for sequential output or `document` to group by document. | `document` |
| `ExternalTimeout` | Number of seconds to wait on an HTTP connection before failing. | `15` |
| `RedirectLimit` | Allowed number of redirects. Use built-in behavior with negative values. | `-1` |
| `StripQueryString` | Enables stripping of query strings from external checks. | `true` |
| `StripQueryExcludes` | List of URLs to disable query stripping on. | `["fonts.googleapis.com"]` |
| `OutputDir` | Directory to store cache and log files in. Relative to executing directory. | `tmp/.htmltest` |
| `OutputCacheFile` | File within `OutputDir` to store reference cache. | `refcache.json` |
| `OutputLogFile` | File within `OutputDir` to store last tests errors. | `htmltest.log` |
| `CacheExpires` | Cache validity period, accepts [go.time duration strings](https://golang.org/pkg/time/#ParseDuration) (…”m", "h"). | `336h` (two weeks) |

  12. Reference: Output and Caching configuration

    master

    Control where htmltest stores its cache and logs, and how long the cache remains valid.

    | Option | Description | Default |
| :-----|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :------ |
| `OutputDir` | Directory to store cache and log files in. Relative to executing directory. | `tmp/.htmltest` |
| `OutputCacheFile` | File within `OutputDir` to store reference cache. | `refcache.json` |
| `OutputLogFile` | File within `OutputDir` to store last tests errors. | `htmltest.log` |
| `CacheExpires` | Cache validity period, accepts [go.time duration strings](https://golang.org/pkg/time/#ParseDuration) (…”m", "h"). | `336h` (two weeks) |