postdoc test


Runs the project's tests with Nightwatch 3.15 or newer, which has to be installed in the project: npm i -D nightwatch@3. Another package can bring in Nightwatch 2, which the command doesn't run.

Besides the tests in the tests directory, it checks every page of the site without any test files. It builds the project, serves the output, runs axe accessibility checks on each page, and tries each page with the keyboard and with larger text. See page checks. HTML files that aren't pages of PostDoc, such as one in the public folder, are left out: they don't load PostDoc's script, so the checks can't tell when they're ready.

Your own tests run first, and the page checks after them, in a Nightwatch run of their own.

Options:

  • --skip-page-checks - runs only the tests in the tests directory.
  • --pages <patterns> - checks only the pages whose URLs match these glob patterns, separated by commas, such as /guide/**,/index.html.
  • --widths <widths> - the window widths to check each page at, in CSS pixels, such as 1280,390, in place of nightwatch.pageChecks.widths.
  • --report <file> - writes what the page checks found to this file, as JSON: each problem with its page, width and check, the problems grouped, how many pages and widths were checked, and whether the checks finished. The checks keep a record as they go, so the report still has what they found if Nightwatch stops on the way.
  • --out-dir <dir> - builds into this directory instead of the configured outputPath, which is then left as it is.
  • --watch - reruns the tests when they change. Page checks don't run in watch mode.
  • Any other option goes to Nightwatch, such as --env firefox or --parallel.

Nightwatch runs with PostDoc's own configuration, which opens the served build and loads nightwatch-plugin-postdoc when the project has it. To run with yours, set nightwatch.config or pass --config; the browsers in nightwatch.browser that it has no environment for are left out. A project's own nightwatch.json or nightwatch.conf.js isn't read by itself, and the command says so.

The page checks run with the same configuration and the same options, apart from those that choose tests or reports, with two changes for a run over a whole site: Nightwatch writes no report files, and the browsers' drivers log only warnings. Nightwatch keeps both in memory, which a site of a few hundred pages fills.

After the checks, the command prints each problem once, with the pages it was found on, so one in a header or a footer doesn't fill the report.

The command exits with Nightwatch's exit code, so failing tests fail a CI job, and with 1 when the build had to leave out a page that couldn't be compiled.

Example

sh
npx postdoc test --pages '/guide/**' --widths 1280,390 --report checks.json