Strict inputs, explicit hosts, stable exit codes.

Commands

vanilla-test coverage [all|node|chrome] [options]

vanilla-test coverage
vanilla-test coverage all
vanilla-test coverage node
vanilla-test coverage chrome

# equivalent short aliases
vanilla-test all
vanilla-test node
vanilla-test chrome

coverage, coverage all, and the all alias run Node first, then Chrome. The node and chrome aliases select one collector. Running vanilla-test with no arguments prints help and exits with status 0.

An ordinary assertion or threshold failure in Node does not discard its report or prevent the Chrome collector from producing its own report.

Repository contributors can use the npm scripts below. Run a script exactly as shown; append CLI options after --.

npm run coverage -- --timeout-ms 60000
npm run coverage:chrome -- --headed
npm run coverage:chrome -- --chrome-path "/opt/google/chrome/google-chrome"

Options

Options may appear once. Unknown arguments, duplicate options, or options missing a value are usage errors.

Configuration

Paths are resolved from the directory containing the configuration file, not from whichever directory contains the installed package.

{
    "entry": "./test/CI.js",
    "reportsDirectory": "./coverage",
    "thresholds": {
        "statements": 100,
        "branches": 100,
        "functions": 100,
        "lines": 100
    },
    "timeoutMs": 30000,
    "node": {
        "include": ["index.js"]
    },
    "chrome": {
        "include": ["index.js"],
        "imports": {},
        "headless": true,
        "executablePath": null
    }
}

When you run only one collector, its sibling configuration object is optional: a Node-only configuration may omit chrome, and a Chrome-only configuration may omit node. The all target requires both objects.

Choose Chrome with executablePath

null is the portable default, not a placeholder. It tells vanilla-test to check CHROME_PATH, standard Google Chrome Stable locations on Windows, macOS, and Linux, then Chrome executable names available on PATH.

{
    "chrome": {
        "include": ["index.js"],
        "imports": {},
        "headless": true,
        "executablePath": null
    }
}

Use a committed string when every machine shares one nonstandard installation. JSON requires Windows backslashes to be escaped:

{
    "chrome": {
        "include": ["index.js"],
        "imports": {},
        "headless": true,
        "executablePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
    }
}

For machine-specific and CI installations, leave the config at null and use an environment or command-line override:

# PowerShell
$env:CHROME_PATH = 'C:\Program Files\Google\Chrome\Application\chrome.exe'
npm run coverage:chrome
npm run coverage:chrome -- --chrome-path 'D:\Browsers\Chrome\chrome.exe'

# macOS or Linux shell
CHROME_PATH=/usr/bin/google-chrome-stable npm run coverage:chrome
npm run coverage:chrome -- --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Keep Chrome's sandbox enabled by default. On an isolated Linux CI runner that cannot provide a usable Chrome sandbox, opt out for that job only:

VANILLA_TEST_CHROME_NO_SANDBOX=1 npm run coverage

Entry result contract

The imported entry may return synchronously or asynchronously. Its result must expose consistent ok and failureCount values:

{ ok: true, failureCount: 0 }
{ ok: false, failureCount: 2 }

Missing, negative, non-integer, or contradictory values are harness failures. This prevents an incomplete or malformed suite from being treated as a successful run.

Path and import safety

• Entry, reports, included source, and browser-import targets must stay inside the configuration root after real-path resolution.
• Include scopes accept positive globs only; absolute paths, parent traversal, and ! negation are rejected.
• Browser import targets must be local files. Remote URLs and protocol-relative URLs are rejected.
• The temporary browser server permits only GET and HEAD, requires its exact loopback Host, denies dotfiles and common secret/key paths, and rejects traversal and link escapes.
• The Chrome page blocks requests outside the bound coverage origin; local responses add CSP, CORP, no-referrer, no-sniff, frame-denial, and no-store headers.
• Unknown configuration keys are errors rather than silently ignored settings.

Exit statuses

Output layout

coverage/
  node/
    .vanilla-test-coverage.json
    index.html
    lcov.info
    coverage-summary.json
    test-results.json
  chrome/
    .vanilla-test-coverage.json
    index.html
    lcov.info
    coverage-summary.json
    test-results.json
    vanilla-test-chrome.png

A collector builds a complete report in a temporary sibling directory. After a valid completed run—even a test or threshold failure—it atomically replaces only a report carrying the matching ownership marker. An unowned directory is refused. Configuration, harness, timeout, collector, or interruption failures clean up staging and preserve the previous known-good report. Running both collectors retains both final reports. The documentation site's coverage page normalizes those summaries and links the complete published reports.

CI recipe

- run: npm ci
- run: npm test
- run: npm run coverage -- --chrome-path "$CHROME_PATH"

Install Google Chrome Stable explicitly in CI and log the exact Node and Chrome versions beside the artifacts. Treat the Node test matrix, coverage collectors, and packed-artifact smoke as separate required gates before publishing quality data.