bombadil browser test #

Run a test with a browser managed by Bombadil.

bombadil browser test [OPTIONS] <ORIGIN> [SPECIFICATION_FILE]

Arguments #

<ORIGIN>

Starting URL of the test. Without --allow-url, exploration stays on the origin’s scheme, host and port. For a file:// origin it stays on that exact file. With one or more --allow-url entries, those define the exploration boundary instead (include the origin there if it should remain allowed).

[SPECIFICATION_FILE]

A custom specification in TypeScript or JavaScript, using the @antithesishq/bombadil package on NPM.

Options #

--output-path <OUTPUT_PATH>

Where to store output data (trace, screenshots, etc.).

--output-path-overwrite

Overwrite any existing trace at --output-path. Without this flag, Bombadil refuses to write when trace.jsonl already exists.

--exit-on-violation

Whether to exit the test when first failing property is found (useful in development and CI).

--width <WIDTH>

Browser viewport width in pixels.

Default: 1024

--height <HEIGHT>

Browser viewport height in pixels.

Default: 768

--device-scale-factor <DEVICE_SCALE_FACTOR>

Scaling factor of the browser viewport, mostly useful on high-DPI monitors when in headed mode.

Default: 1

--instrument-javascript <INSTRUMENT_JAVASCRIPT>

What types of JavaScript to instrument for coverage tracking. Comma-separated list of: “files”, “inline”.

Default: files,inline

--time-limit <TIME_LIMIT>

Maximum time to run the test. Accepts a number with a unit suffix: s (seconds), m (minutes), h (hours), or d (days).

--chrome-grant-permissions <CHROME_GRANT_PERMISSIONS>

Comma-separated list of Chrome permissions to grant.

Default: local-network-access,local-network,loopback-network

--chrome-virtual-time-policy <CHROME_VIRTUAL_TIME_POLICY>

Optional virtual time policy for Chrome, used to speed up execution of timer-heavy applications. One of: Advance, Pause, PauseIfNetworkFetchesPending.

--header <KEY=VALUE>

Extra HTTP header to send with all browser requests, in KEY=VALUE format. Can be specified multiple times.

--cookie <SET-COOKIE>

Cookie to set in the browser before testing. Accepts plain NAME=VALUE (scoped to the origin) or Set-Cookie syntax with attributes such as Domain, Path, Secure, and HttpOnly. Unlike --header, these become real browser cookies. Can be specified multiple times.

--allow-url <MATCH_PATTERN>

Exploration boundary as Chrome extension match patterns, e.g. *://*.example.com/*. Replaces the implicit origin match pattern. For the pattern syntax, see Match patterns.

--reproduce <TRACE_FILE>

Reproduce a previous test run from a trace file, instead of random exploration. Mutually exclusive with --time-limit and --exit-on-violation.

--headless

Whether the browser should run in a visible window or not.

--no-sandbox

Disable Chromium sandboxing.

-h, --help

Print help.

Examples #

Test a website using the default specification:

bombadil browser test https://example.com

Use a custom specification and stop at the first violation:

bombadil browser test --exit-on-violation https://example.com spec.ts

Run headless for five minutes:

bombadil browser test --headless --time-limit 5m https://example.com

Grant specific Chrome permissions:

bombadil browser test --chrome-grant-permissions geolocation,notifications https://example.com

Speed up a timer-heavy app by automatically advancing virtual time in Chrome:

bombadil browser test --chrome-virtual-time-policy Advance https://example.com

Reproduce a test run (best-effort, fails on divergence):

bombadil browser test --reproduce my-test https://example.com