Qualflare reporter options and variables

Every option and QUALFLARE_ environment variable the Qualflare reporters share, with defaults, and which ones reach the launch when qf uploads it.

This page lists the settings every Qualflare reporter shares, with their environment variables and defaults, and which of them reach the launch when qf <identifier> collect uploads the results; the default results folder is qualflare-results.

Settings at a glance

Setting	Environment variable	Default	On the launch
Results folder	`QUALFLARE_OUTPUT_DIR`	`qualflare-results`	— (the folder `qf` reads)
Environment	`QUALFLARE_ENVIRONMENT`	`development`	Yes, unless the upload sets `--environment` or `QF_ENVIRONMENT`
Platform	`QUALFLARE_PLATFORM` (not the JavaScript reporters)	Varies by reporter	Yes, unless the upload sets `--platform` or `QF_PLATFORM`
Language	`QUALFLARE_LANGUAGE`	`en-US`	No: set `--lang` or `QF_LANGUAGE`
Milestone	`QUALFLARE_MILESTONE`	None	No: set `--milestone` or `QF_MILESTONE`
Branch and commit	`QUALFLARE_BRANCH`, `QUALFLARE_COMMIT`	Detected	No: `qf` detects its own, or set `--branch`, `--commit`, `QF_BRANCH`, `QF_COMMIT`
Run ID	`QUALFLARE_RUN_ID`	The CI run ID, else a random ID	`qf` keeps the newest run
Shard index	`QUALFLARE_SHARD_INDEX`	Detected, or none	Yes, per test
Turn off	`QUALFLARE_ENABLED`	`true`	—
CI details	Detected	Detected	Yes

Where to set an option

Reporters	Where	Precedence
Playwright, Cypress, Jest, Vitest, Mocha, Cucumber.js, WebdriverIO, Appium, Detox	An options object in the framework's config, or the environment variable	Option → `QUALFLARE_` → `QF_` (environment, language, milestone, branch, commit, debug) → detection → default
pytest	`qualflare_*` keys in `pytest.ini`, `pyproject.toml`, `setup.cfg` or `tox.ini`	Ini key → `QUALFLARE_*` → detection → default
Go, Maestro	Command-line flags of `qualflare-go` and `qualflare-maestro`	Flag → `QUALFLARE_*` → CI → git → default
JUnit 5, TestNG	`qualflare.*` system properties	System property → `QUALFLARE_*` → default
Espresso	`qualflare.*` instrumentation arguments	Argument → system property → `QUALFLARE_*` → default
Flutter	None: `qualflare_flutter` has no options	—

WebdriverIO and Appium name the folder resultsDir (QUALFLARE_RESULTS_DIR, then QUALFLARE_OUTPUT_DIR), because WebdriverIO's own outputDir holds its logs.
No reporter takes a token: qf login holds it.
An empty value falls through to the next source instead of winning.

Settings

Results folder

The default is qualflare-results (./qualflare-results in the JavaScript reporters). Playwright resolves a relative path against the folder of its config file. Every process writes a uniquely named file, so shards can share one folder.

Pass the same folder to qf <identifier> collect. qf reads the .json files directly inside it, not its subfolders: see Collect a directory.

Environment

The value is an environment's Identifier, which is case-sensitive, not its name: Staging in the app is usually staging. New projects have development, staging, production and qa (Default environments).

A wrong value doesn't fail the test run, because the reporter checks nothing. The upload fails with environment "Staging" does not exist in this project (HTTP 400, exit code 1), and no launch is created.

qf uses, in order: --environment, QF_ENVIRONMENT, the environment the reporter wrote, then development.

Platform

The values are android, ios, desktop, web and api. Maestro, Detox, WebdriverIO and Appium detect the platform from the device. Otherwise the default is web in the JavaScript reporters, api in pytest, Go, JUnit 5 and TestNG, and android in Espresso.

qf takes the report's platform when the upload sets neither --platform nor QF_PLATFORM, and the value is one of the five.

Branch, commit, language and milestone

The reporters write these into their reports, but qf 0.4.0 doesn't read them from a report. Set them on the upload: --branch, --commit, --lang and --milestone, or QF_BRANCH, QF_COMMIT, QF_LANGUAGE and QF_MILESTONE in the job that runs qf. Without them, qf detects the branch and commit from CI variables and git.

The JavaScript reporters read the same QF_* names as fallbacks, so one set of variables in the job covers both.

A milestone set only in the reporter isn't applied

A launch is linked to a milestone only when the upload passes --milestone or QF_MILESTONE. A milestone you set in the reporter's options is written to the report and ignored.

Every upload flag and its default is in Launch metadata.

Run ID

The JavaScript reporters, qualflare-pytest, qualflare-go and qualflare-maestro write a run ID into each report. In CI it is the provider's run ID, which every shard of the run shares; elsewhere it is a new random ID per process, except that WebdriverIO and Appium workers derive one shared ID from the wdio run launcher process.

qf uploads the reports of the newest run in the folder and ignores older ones, unless you pass --allow-mixed-runs. A report without a run ID is always uploaded. Set QUALFLARE_RUN_ID only when your CI isn't detected and you shard. The Go reporter adds the GitHub run attempt, so a re-run gets its own launch.

Shard index

A label for which shard ran each test, 0-based. Playwright, Jest, Vitest, Mocha and Cucumber.js read it from their own --shard i/N; pytest from the xdist worker; WebdriverIO from --shard. Set QUALFLARE_SHARD_INDEX elsewhere. qf merges by folder contents, not by this number. See Shards.

Turn a reporter off

QUALFLARE_ENABLED=false makes the reporter write nothing; the tests run as before. The JVM and Espresso reporters read 0, false, no and off as off and anything else as on.

Attachment limits

In the JavaScript reporters, maxAttachmentBytes (QUALFLARE_MAX_ATTACHMENT_BYTES, default 5000000) skips a larger attachment with a warning, and maxTotalAttachmentBytes (QUALFLARE_MAX_TOTAL_ATTACHMENT_BYTES, default 10000000) caps a run's inline attachments. Screenshots, videos and traces are copied to the results folder and don't count.

Uploading videos and traces is the upload's choice: Upload screenshots, videos and traces.

Debug output

In the JavaScript reporters except Cypress, QUALFLARE_DEBUG or QF_DEBUG (default false) prints extra detail on stderr. @qualflare/cypress has no debug option.

CI details

The JavaScript reporters detect the CI provider, build number, run URL and pull request number on GitHub Actions, GitLab CI, CircleCI, Buildkite, Jenkins, Azure Pipelines and Bitbucket Pipelines; Jenkins gives no pull request number. qualflare-pytest, qualflare-go and qualflare-maestro detect them on GitHub Actions, GitLab CI, CircleCI and Jenkins.

qf copies them to the launch, which shows them as chips in its header: see Launch detail view.

Metadata from your tests

Call	What it records
Label	A name and a value
Link	A URL with the type `issue`, `tms` or `custom` and an optional name; the server accepts only those three types
Tag	A tag
Priority	`low`, `medium`, `high` or `critical`; `info` is stored as `low`, and any other value as no priority
Step	A named step, which can nest
Parameter	A name and value on a step or the test; with masked, the reporter drops the value before writing the report, and the server doesn't redact values itself
Attachment	A file with a MIME type

Each reporter's page shows its calls. A call made outside a running test is dropped, not attached to the next test, and most reporters print a warning. In Go, such a call doesn't compile. Maestro takes its metadata from the flow's YAML, so it has no calls.

Errors

environment "Staging" does not exist in this project: the reporter's environment is not an Identifier. Fix it, or pass --environment: see Environment and Troubleshoot qf and CI uploads.
ignored N file(s) from M earlier run(s) (--allow-mixed-runs to include them): the folder holds older reports. They stay on disk and aren't uploaded.
directory "<dir>" contains no .json report files: the reports are in a subfolder, or the reporter wrote none. Check that it is registered and enabled.
Screenshots arrive as files that can't be downloaded: qf is older than 0.1.24, which first reads image paths from reports. Upgrade: Install the CLI.

Guides: Reporters · Sharded runs and result directories
Reference: Launch metadata · Environments · Configuration and environment variables
CLI and API: Authenticate with qf login

Reporter configuration