Configuration reference

This is the full table. The per-framework pages (Playwright, WebdriverIO, Jest, Vitest) walk through the wiring; this page is what you read when you want to know what every knob does.

Shared options

Every reporter accepts these.

Required

Option	Type	Env equivalent	Description
url	string	BRITTLE_URL	URL of your self-hosted Brittle hub, e.g. http://localhost:3100 or https://brittle.your-domain.com. Trailing slashes are stripped.
token	string	BRITTLE_TOKEN	Project token. Mint from Manage → Projects → [your project] → Tokens.

Pass inline or via env vars; env wins (handy in CI).

Run grouping

Option	Type	Default	Description
runName	string	CI build ID → run-{ppid}-{date}	The key used to converge parallel workers / shards onto one Run row. Falls back to BRITTLE_RUN_NAME then the CI build ID.
target	string	none	Deployment label for separate-repo flows ("prod", "staging", "app@1.42.0"). Empty for same-repo flows.
tags	string[]	[]	Run-level tags shown on the Runs page.

Git context

Each of these has an explicit option and an env-var fallback. The reporter auto-detects all of them from git unless you set detectGit: false.

Option	Type	Description
branch	string	Branch the run is on. Falls back to git symbolic-ref.
commitSha	string	Commit SHA. Falls back to git rev-parse HEAD.
commitMessage	string	Subject line of the commit. Falls back to git log -1 --format=%s.
commitAuthor	string	Commit author name + email. Falls back to git log -1 --format=%an <%ae>.
repoUrl	string	Git remote URL. Falls back to git remote get-url origin. Used to deep-link runs to commits.
prUrl	string	Pull request URL. No git auto-detection. Set this from CI env if you want PR links.
detectGit	boolean	Default true. Set to false on sparse / shallow / sandboxed CI where git isn’t reliable.

In CI it’s usually safer to set the values explicitly from environment variables your provider supplies (GITHUB_SHA, GITHUB_REF_NAME, CI_COMMIT_SHA). They’re guaranteed correct on shallow checkouts.

Behaviour

Option	Type	Default	Description
silent	boolean	false	Suppress all reporter output. Errors still print to stderr.
timeoutMs	number	30000	Per-request HTTP timeout in milliseconds. Bump for slow networks; failed requests print a warning and the next test continues.

Diagnostic env vars

Variable	Description
BRITTLE_DEBUG	Set to 1 to enable verbose per-test logging on stderr. Off by default.
HTTPS_PROXY	Standard env var. Honoured for the reporter’s outbound calls.
NO_PROXY	Standard env var. Honoured.

Playwright-specific

In addition to the shared options:

Option	Type	Description
runMetadata	object	Free-form metadata posted at run-upsert time. Same shape as the explicit git fields above; useful for shipping CI-supplied values in one block.
browser	'chromium' | 'firefox' | 'webkit'	Browser identifier stamped on each session. Defaults to the Playwright project’s use.browserName.

WebdriverIO-specific

Option	Type	Description
screenshotOnFailure	boolean	When true, calls browser.takeScreenshot() after a failing test and attaches the PNG.

Jest-specific

None. Jest uses only shared options.

Vitest-specific

None. Vitest uses only shared options.

Inline vs env config

You can split however you want. Common patterns:

Everything from env (recommended for CI):

['@brittlehq/playwright-reporter', {}]

The reporter reads BRITTLE_URL / BRITTLE_TOKEN / BRITTLE_RUN_NAME from the environment. Run with:

BRITTLE_URL=https://brittle.your-domain.com \
BRITTLE_TOKEN=brt_svc_xxxx \
BRITTLE_RUN_NAME="$GITHUB_RUN_ID" \
pnpm test

Inline overrides for explicit metadata:

['@brittlehq/playwright-reporter', {
  url: process.env.BRITTLE_URL,
  token: process.env.BRITTLE_TOKEN,
  tags: ['nightly', 'smoke'],
  target: 'staging',
}],

Inline options always override env. Reach for explicit only when you want a CI-time decision baked into the config.

Next steps

• Reporter overview for what each reporter does and how they group runs.
• Installation for the one-line install or manual Docker Compose walkthrough.