Skip to content
The docs are now organized by product area. Old links still work. Report a broken link

Upload results with qf collect

Upload test results to Qualflare with the qf collect command: syntax, flags, launch metadata and exit codes, for JUnit XML, pytest, Jest, Playwright and more.

Last updated

qf <identifier> collect is the Qualflare CLI command that parses test result files and uploads them as one launch. It reads 27 frameworks and 4 generic formats, and it gives up after 30 seconds unless you raise --timeout.

Uploaded screenshots, videos and traces are deleted after 30 days

Screenshots, videos and trace files that qf <identifier> collect uploads with your test results are deleted 30 days after upload and can't be restored. Download any you need to keep before then. See Data Retention.

Basic syntax

qf <identifier> collect [files...] [flags]

<identifier> is a project alias you saved with qf login. See Authenticate with qf login for setup.

Arguments

ArgumentDescription
files...One or more test result files or directories. qf expands a quoted glob such as "test-results/*.xml" itself. In a glob qf expands, ** is not recursive: it matches one directory level, like *. An unquoted glob is expanded by your shell first. A glob that matches nothing is an error. A directory adds the .json files directly inside it, unless it holds Allure results; see Collect a directory.

Examples

# Collect a single JUnit XML file
qf myapp collect results.xml --format junit

# pytest: write JUnit XML with --junitxml, then collect it
pytest --junitxml=pytest-report.xml
qf myapp collect pytest-report.xml --format python

# Auto-detect format from file
qf myapp collect playwright-results.json

# Collect multiple files with glob pattern
qf myapp collect test-results/*.xml --format junit

# Specify environment and git metadata
qf myapp collect results.xml --environment production --branch main --commit abc123

# Dry run - parse without uploading
qf myapp collect results.xml --dry-run

# Output parsed results as JSON (use with dry-run)
qf myapp collect results.xml --dry-run --output json

For every format and its --format value, see Supported formats.

Flags

Some flags also have an environment variable. See Configuration.

FlagShortTypeDefaultDescription
--format-fstring"" (auto-detect)Test framework format. Use qf list-formats to see all supported formats.
--environment-estringdevelopmentIdentifier of an environment that exists in the project (e.g., development, staging, production, qa)
--langstringen-USLanguage of the launch. Must be a language tag Qualflare supports (e.g., en-US, de-DE, ja-JP).
--platformstringapiPlatform the tests ran on. One of android, ios, desktop, web, api.
--branchstring""Git branch name (e.g., main, develop, feature/login)
--commitstring""Git commit hash for tracking which code version was tested
--milestoneint640 (none)Milestone sequence number to link this launch to.
--shardboolfalseTreat each input file as one shard of a parallel test run. See Number shards with --shard.
--no-capture-outputboolfalseStrip captured stdout/stderr and custom test properties before uploading.
--debugboolfalseLog full HTTP request/response detail to stderr (token redacted).
--timeoutduration30sOverall deadline for parsing and uploading the report, retries included. Go duration, e.g. 90s, 2m. See --timeout.
--dry-runboolfalseParse files without uploading to Qualflare. Useful for validation and debugging.
--output-ostring""Output format for dry-run mode. Currently supports json.
--upload-artifactsstring"" (screenshots only)Artifact kinds to add to the default (screenshots): video, trace. image (screenshots) is accepted and already on. none uploads no artifacts. Also set by QF_UPLOAD_ARTIFACTS. See Upload screenshots, videos and traces.
--artifacts-dirstring""Directory of artifacts a framework left on disk, attached to the matching test cases. Applies to Detox reports. See Attach Detox artifacts.
--allow-mixed-runsboolfalseUpload report files from different runs as one launch. See Collect a directory.
--warn-on-plan-limitboolfalseWhen a plan limit refuses the upload, print a warning and exit 0 instead of 4. The results are not uploaded. Also set by QF_WARN_ON_PLAN_LIMIT. See --warn-on-plan-limit. qf ≥ 0.7.0 (requires qf 0.7.0 or later)

Flag descriptions

--format / -f

Specifies the test framework format. If not provided, the CLI attempts to auto-detect the format based on file content and extension.

qf myapp collect results.xml --format junit
qf myapp collect results.json --format playwright

Every value: Supported formats.

--environment / -e

The Identifier of the environment the tests ran against. The environment must already exist in the project: collect does not create it. New projects start with development, staging, production and qa. To add one, open Settings → Environments in your project and click Create Environment. Without the flag, qf uses QF_ENVIRONMENT, then the environment a native reporter wrote into its report, then development.

qf myapp collect results.xml --environment production
qf myapp collect results.xml --environment staging

An unknown environment fails the whole upload with exit code 1:

$ qf myapp collect results.xml --environment dev
Error: failed to process test results: send: environment "dev" does not exist in this project (status: 400) [request_id: …]

--lang

Sets the language of the launch, which you can filter launches by. The value must be a language tag Qualflare supports, such as en-US, de-DE or ja-JP. An unsupported tag fails the upload. Without the flag, qf uses QF_LANGUAGE, then en-US.

qf myapp collect results.xml --lang de-DE
qf myapp collect results.xml --lang ja-JP

--platform

Labels the test run with the platform it ran on. Useful for separating mobile, desktop, and API results in the same project.

qf myapp collect espresso-results.xml --platform android
qf myapp collect xctest-results.xml --platform ios

--branch and --commit

Git metadata for tracking which code version was tested. Enables integration with Git workflows.

qf myapp collect results.xml --branch main --commit a1b2c3d

In CI/CD, these are often auto-populated from common environment variables (see CI/CD Integration):

# GitHub Actions
qf myapp collect results.xml --branch ${GITHUB_REF_NAME} --commit ${GITHUB_SHA}

# GitLab CI
qf myapp collect results.xml --branch ${CI_COMMIT_REF_NAME} --commit ${CI_COMMIT_SHA}

--milestone

Links this launch to a milestone by its sequence number. Useful for tracking release-health across multiple launches tied to the same milestone.

qf myapp collect results.xml --milestone 12

--timeout

The overall deadline for one collect: parsing the files and uploading the report, retries included. Default is 30 seconds. Raise it for large reports or slow networks.

qf myapp collect results.xml --timeout 2m  # 2 minutes

Screenshot and video uploads are not cut off by this deadline: each one gets its own 5-minute limit. The deadline starts when collect starts, though, so the time they take still counts against it. Raise --timeout when you upload videos, traces or many screenshots. QF_TIMEOUT (default 120s) caps each single HTTP request, so raise it as well only when one request takes longer than two minutes. See Retry & Timeout.

--dry-run

Parse and validate test files without uploading. Useful for:

  • Validating file format
  • Debugging parsing issues
  • Previewing what will be collected
qf myapp collect results.xml --dry-run
# Output: OK Test results parsed successfully (dry run)

--output / -o

Used with --dry-run to output parsed results as JSON. Useful for debugging and integration.

qf myapp collect results.xml --dry-run --output json

--no-capture-output

Strips captured system-out/system-err output, and any non-structural custom test property (e.g. a JUnit or pytest <property>, or TestCafe fixture.*/test.* metadata), before uploading. Properties a parser generates itself to describe the test (file path, duration, etc.) are still uploaded — only custom, test-authored properties and captured console output are removed.

qf myapp collect results.xml --no-capture-output

Use this when your test output may contain sensitive data (secrets, tokens, PII) that shouldn't leave your CI environment.

--debug

Logs the full HTTP request and response for the upload to stderr, with the auth token redacted. Useful when diagnosing upload failures.

qf myapp collect results.xml --debug

--warn-on-plan-limit

qf ≥ 0.7.0 (requires qf 0.7.0 or later)

The --warn-on-plan-limit flag keeps a CI job green when the workspace has reached a plan limit: collect prints a warning to stderr and exits 0 instead of failing with exit code 4. It is off by default. QF_WARN_ON_PLAN_LIMIT=true (or 1) turns it on for every collect, and --warn-on-plan-limit=false turns it off for one command.

qf myapp collect results.xml --warn-on-plan-limit

The warning gives the server's reason and the request ID:

warning: test results were NOT uploaded: this workspace has reached a plan limit. Not failing the build because --warn-on-plan-limit or QF_WARN_ON_PLAN_LIMIT is set. Reason from Qualflare: Launches quota exceeded (100/100) [request_id: …]

The results of that run are not in Qualflare. All the files of one collect, shards included, go up as one launch that is accepted or refused as a whole. Screenshots upload before the report, so some of them may already be stored. --quiet does not hide the warning.

The flag covers only the plan limits on monthly test reports, test cases and test suites. Everything else still fails as before: an invalid token, access denied, a frozen workspace, full storage, an inactive subscription, a rejected report, and network or server errors. See What happens at a limit.

Global flags

These flags are available on all commands, as are --debug and --no-capture-output (all four, with their variables: Global flags):

FlagShortDescription
--verbose-vEnable detailed debug output
--quiet-qSuppress all non-error output

Launch metadata

Every launch that qf <identifier> collect creates records an environment, a language, a platform, the git branch and commit and, optionally, a milestone.

FieldFlagVariableDefaultRule
Environment--environmentQF_ENVIRONMENTThe value a native reporter wrote, then developmentThe Identifier of an environment that exists in the project
Language--langQF_LANGUAGEen-USA language tag Qualflare supports
Platform--platformQF_PLATFORMThe value a native reporter wrote, then apiOne of android, ios, desktop, web, api. qf checks --platform before it uploads; a bad QF_PLATFORM is refused by the server
Branch and commit--branch, --commitQF_BRANCH, QF_COMMITCI variables, then the local git checkout (CI auto-detection)None
Milestone--milestoneQF_MILESTONENoneThe sequence number of an existing milestone. Values below 1 are ignored

An environment, milestone or language that doesn't exist fails the whole upload with 400 and exit code 1, and no launch is created. The server names the value it refused, and qf refuses a bad --platform before it sends anything:

environment "staging" does not exist in this project
milestone #12 does not exist in this project
language "xx-XX" is not supported
invalid --platform "linux": must be one of android, ios, desktop, web, api
The header of a launch uploaded with qf collect, with its status, environment, branch and qf version chips.
A launch uploaded with qf collect shows its environment, branch and qf version in its header.

Fixes: Troubleshoot qf and CI uploads.

Exit codes

CodeMeaning
0Success - test results collected or validated successfully
1Generic error - file not found, parse error, invalid configuration, or invalid arguments/flags
3Auth error - 401, invalid or expired token
4Forbidden - 402/403, quota exceeded or plan/access denied
5Not found - 404
7Transient error - 429 or 5xx from the server; safe to retry

With --warn-on-plan-limit, an upload refused at a plan limit exits 0 instead of 4. What to do for each: Exit codes.

Error handling

The CLI provides clear error messages for common issues:

File not found

$ qf myapp collect missing.xml
Error: file does not exist: missing.xml

Invalid format

$ qf myapp collect results.xml --format unsupported
Error: unsupported format: unsupported. Use 'qf list-formats' to see supported formats

Parse error

$ qf myapp collect invalid.xml
Error: failed to process test results: failed to parse file invalid.xml: <parser error>

Not logged in

$ qf myapp collect results.xml
Error: no identifier "myapp" configured. Run 'qf login myapp' to sign in. (See 'qf projects' for the list.)

Network error

$ qf myapp collect results.xml
Error: failed to process test results: connection refused

The causes and fixes for these and other errors: Troubleshoot qf and CI uploads.

Collecting a directory

Pass a directory to upload every .json report directly inside it; a directory with a *-result.json file directly inside it is read as Allure results instead, and its other .json files are not uploaded. collect uploads the newest run in a directory and any report without a run ID: see Sharded runs and result directories.

Artifacts

Screenshots in a report upload by default; videos and Playwright traces upload only with --upload-artifacts video,trace. See Upload screenshots, videos and traces.

When a file would take the workspace past its storage limit, qf skips that file and still uploads the results, and collect exits with code 0. For each file it skips, it prints a skipping <kind> attachment line with the server's Storage is full message, and the case keeps a placeholder for the file. See When storage is full.

Upload limits

Each input file can be up to 100 MB, and the report qf sends must fit the server's 10 MB limit. See Size limits.

Sharding parallel test runs

To merge parallel or sharded CI jobs into one launch, collect all their results in one qf <identifier> collect call; --shard numbers the files by position. See Sharded runs and result directories.

Supported formats

The qf <identifier> collect command supports 27 frameworks and 4 generic formats across six categories. Use the --format flag to specify your framework, or let the CLI auto-detect it. Run qf list-formats to print every --format value the CLI accepts.

Each card opens the page of the framework's Qualflare reporter where there is one, and the format's section in Supported formats otherwise.

Native reporters

Qualflare publishes native reporters for Playwright, Cypress, Jest, Vitest, Mocha, Cucumber.js, WebdriverIO, Appium, Detox, Espresso, Maestro, Flutter, pytest, Go, JUnit 5 and TestNG. Each one writes its results to files that qf <identifier> collect uploads, and none makes a network call: see Reporters.

What a native reporter adds

A native reporter records per-attempt retry history, steps, attachments and the metadata a test sets about itself, which JUnit XML can't carry: see What a native reporter adds.

Allure results

qf ≥ 0.4.0 (requires qf 0.4.0 or later)

Pass an Allure 2 results directory, for example qf <identifier> collect allure-results/: how qf reads it is in Allure results, and the steps are in Upload Allure results.

Usage examples

CI/CD integration

Collect test results as part of your CI/CD pipeline (see CI/CD Integration for full platform examples):

# GitHub Actions
- name: Collect test results to Qualflare
  run: |
    qf login ci --force
    qf ci collect test-results/*.xml
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
    QF_BRANCH: ${{ github.ref_name }}
    QF_COMMIT: ${{ github.sha }}

Multiple test suites

Collect results from multiple test types:

# Unit tests
qf myapp collect unit-results.xml --format junit --environment qa

# E2E tests
qf myapp collect e2e-results.json --format playwright --environment qa

# Security scan
qf myapp collect security-report.json --format trivy --environment qa

Dry run validation

Validate your test results before collecting:

# Validate file can be parsed
qf myapp collect results.xml --format junit --dry-run

# Preview what will be sent
qf myapp collect results.xml --format junit --dry-run --output json

Verbose debugging

Enable verbose output for debugging:

qf myapp collect results.xml --verbose
# Prints to stderr:
# Processing 1 test result file(s)...
# POST https://api.qualflare.com/api/v1/collect
# OK Test results collected successfully

Related