bombadil browser test-external #

Run a test with an externally managed browser or Electron app (e.g. chromium --remote-debugging-port=9992).

bombadil browser test-external [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.

--remote-debugger <REMOTE_DEBUGGER>

Address to the remote debugger’s server, e.g. http://localhost:9222.

--create-target

Whether Bombadil should create a new tab and navigate to the origin URL in it, as part of starting the test (this should probably be false if you test an Electron app).

-h, --help

Print help.

Examples #

Start Chromium (or an Electron app) with remote debugging enabled, and launch a test against the existing open target:

bashchromium --remote-debugging-port=9222 https://example.com
bombadil browser test-external --remote-debugger http://localhost:9222 https://example.com