Skip to main content

CLI Reference

Status: Stable

The design-tests binary runs the suite, builds the report, and reports the installed version. Run it through your package manager so the local install is used:

pnpm exec design-tests --version

run​

Capture screenshots, compare them against the baseline, and write the results.

pnpm exec design-tests run --config .designTests.js --all
OptionDescription
-c, --config <path>Path to the configuration file. Defaults to .designTests.js, then .designTests.ts.
-p, --project <key>Project key to test. The PROJECT environment variable sets the same value.
--allRun every project in the configuration.
--workers <number>Number of parallel browser workers. Overrides playwright.workers.
--set <key.path>=<value>Override any configuration value. Repeatable.
--debugHeaded browser and verbose logs.
--fail-on-changesExit 1 when visual changes are found. Without it the command exits 0 whenever the run completes.

Select one project or all of them — a run with neither --project nor --all has nothing to do.

# One project, eight workers, headed
pnpm exec design-tests run --config .designTests.js --project ewz-web --workers 8 --debug

# Project by environment variable
PROJECT=kus-contracts pnpm exec design-tests run --config .designTests.js

# Override configuration values
pnpm exec design-tests run --config .designTests.js --all \
  --set projects.bfh.url=http://localhost:3000 \
  --set playwright.workers=4

Exit codes​

CodeMeaning
0The run completed and the report was written. Visual differences do not change this unless --fail-on-changes is set.
1Visual differences were found. Only with --fail-on-changes.
2The run failed to complete.

Local work wants the default, where the report is the output and the exit code is noise. A CI quality gate wants --fail-on-changes. Jenkins derives build status from reg.json rather than from the exit code, so the flag matters there only if you want the build to stop.

report​

Generate the HTML diff report from results that already exist on disk. run writes the report itself; this command rebuilds it without re-capturing.

pnpm exec design-tests report --config .designTests.js
OptionDescription
-c, --config <path>Path to the configuration file. Defaults to .designTests.js, then .designTests.ts.
-p, --project <key>Project key, used to resolve directories.
-o, --output <path>Output directory. Defaults to reportDir from the configuration.
--url-prefix <prefix>Prefix prepended to image URLs in the report. Needed when the report is served from a path that differs from where it was written — see Jenkins Resource Root URL.

debug​

Registered but not implemented. It prints a notice and exits 0. Use run --debug instead, which opens a headed browser and turns on verbose logging.

Configuration overrides​

Every configuration value is overridable from outside the file, in this precedence:

  1. --set flags
  2. DESIGN_TESTS__* environment variables
  3. The configuration file
  4. Built-in defaults

Environment variables use __ to separate path segments and are case-insensitive:

DESIGN_TESTS__PLAYWRIGHT__WORKERS=8 pnpm exec design-tests run --config .designTests.js --all
DESIGN_TESTS__PROJECTS__BFH__URL="http://localhost:3000" pnpm exec design-tests run --config .designTests.js --project bfh

Values are coerced to the type the schema expects and then validated, so a bad type or an invalid URL fails immediately with a message naming the key.

Set environment variables inline on the command rather than exporting them. An inline assignment keeps the command reproducible and scoped to that one run.