Using API
Validating files
import { HtmlValidate } from "html-validate";
const htmlvalidate = new HtmlValidate();
const report = htmlvalidate.validateFile("myfile.html");
console.log("valid", report.valid);
if (!report.valid) {
console.log(report.results);
}
validateFile
is a high-level API which automatically locates configuration
files, load plugins, runs any transformations etc and is very similar to using
the CLI tool (in fact, the CLI tool uses this very API).
A configuration object may optionally be passed to the HtmlValidate
constructor:
const htmlvalidate = new HtmlValidate({
extends: ["html-validate:recommended"],
});
If set, it will be used as configuration unless a configuration could be read from .htmlvalidate.json
files.
Set root: true
to prevent configuration files to be searched.
Validating strings and other sources
In addition to validateFile
there is also validateString
and
validateSource
. Unlike validateFile
no configuration files will be searched
from the filesystem and the full configuration must be passed to the
HtmlValidate
constructor.
const report = htmlvalidate.validateString("<div>lorem ipsum</span>");
console.log(report.results);
const report = htmlvalidate.validateSource({
/* markup to validate */
data: "<div>lorem ipsum</span>",
/* filename to put in report, content is not read */
filename: "myfile.txt",
/* original source location, i.e. at what position was markup extracted from
* in original file. */
line: 12,
column: 8,
});
console.log(report.results);
Handling multiple files
To validate multiple files you need to call validateFile
for each one,
obtaining a report for each one. The reports can then be merged together,
forming a new Report
object.
const report1 = htmlvalidate.validateFile("myfile.html");
const report2 = htmlvalidate.validateFile("anotherfile.html");
/* merge reports together to a single report */
const merged = Reporter.merge([report1, report2]);
/* valid is true only if all reports are valid */
console.log("valid", merged.valid);
/* results holds all files */
if (!merged.valid) {
console.log(merged.results);
}
Formatting reports
HTML-validate comes with a number of builtin formatters:
checkstyle
codeframe
json
stylish
text
Formatters work on the results
property in a report and all returns a
formatted string:
import { HtmlValidate } from "html-validate";
import text from "html-validate/dist/formatters/text";
const htmlvalidate = new HtmlValidate();
const report = htmlvalidate.validateFile("myfile.html");
console.log(text(report.results));
Using the CLI API there is a factory function to retrieve formatters (see
html-validate --help
for details about the format):
import { getFormatter } from "html-validate/dist/cli/formatter";
const stylish = getFormatter("stylish");
console.log(stylish(report));
In addition, any ESLint compatible reporter will work:
const stylish = require("eslint/lib/formatters/stylish");
console.log(stylish(report.results));
Configuration cache
HtmlValidate
is mostly stateless, it only acts on the input source and its
configuration.
However, for performance configuration is cached (per instance) and must be
flushed if configuration is changed. Normally this wont matter but when writing
integrations with tools it might be desirable to keep a single instance of
HtmlValidate
around and in that case the cache needs to be flushed if
configuration changes are detected.
/* flush everything */
htmlvalidate.flushConfigCache();
/* flush configuration for a single file */
htmlvalidate.flushConfigCache("myfile.html");
Unit testing
If using jest to write tests there is a couple of helpers to assist writing tests:
import { HtmlValidate } from "html-validate";
import "html-validate/jest";
const config = {
rules: {
"my-rule": "error",
},
};
test("should frobnicate a tux", () => {
const htmlvalidate = new HtmlValidate(config);
const report = htmlvalidate.validateString("...");
expect(report).toBeValid();
});
test("should not frobnicate a flux", () => {
const htmlvalidate = new HtmlValidate(config);
const report = htmlvalidate.validateString("...");
expect(report).toBeInvalid();
expect(report).toHaveError("my-rule", "the tux should not be frobnicated by a flux");
});
CLI tools
The CLI interface can be wrapped using the CLI
class.
const cli = new CLI({
configFile: argv.configFile,
rules: argv.rules,
});
const htmlvalidate = cli.getValidator();
const formatter = cli.getFormatter(argv.formatter);
const files = cli.expandFiles("**/*.html");
const report = htmlvalidate.validateMultipleFiles(files);