TestOps logo
Try TestOps

Command-line tool - allurectl

allurectl is the command-line entry point for the TestOps upload and selective-execution workflows. Use it when you need a CI-agnostic way to send results to TestOps, when your pipeline should stream results during execution, or when a TestOps-driven launch needs to pass a test plan into the test runtime.

This page focuses on the supported watch, upload, and selective-run workflows that appear throughout the TestOps docs.

Supported platforms

Download the binary that matches your operating system and processor architecture from the latest allurectl release.

Examples of the published binaries include:

  • macOS Intel: allurectl_darwin_amd64
  • macOS Apple silicon: allurectl_darwin_arm64
  • Linux x64: allurectl_linux_amd64
  • Linux ARM64: allurectl_linux_arm64
  • Windows x64: allurectl_windows_amd64.exe

Example download for Linux x64:

wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -O ./allurectl
chmod +x ./allurectl

Before you run allurectl

Create a TestOps API token first:

  1. In Allure TestOps, click your avatar and open API Tokens.
  2. Click + Token.
  3. Create the token and copy it.

For the detailed token workflow, see User menu and API tokens.

Choose the right mode

allurectl operates in two practical modes:

  • local or manual upload mode when you run it outside a supported CI context;
  • CI-aware mode when the surrounding environment exposes CI metadata or when TestOps starts a job run and injects the related service variables.

In CI-aware mode, TestOps can connect uploaded results to the correct launch, job run, and pipeline context instead of treating the upload as an isolated local session.

When TestOps starts a CI-backed job, the injected job-run context takes precedence over locally supplied launch naming. In practice this means ALLURE_JOB_RUN_ID and the related service variables should be allowed to flow through untouched to the process that runs allurectl.

Shared environment variables

These variables are the common contract for both watch and upload:

Environment variable Meaning
ALLURE_ENDPOINT Base URL of the TestOps instance
ALLURE_TOKEN TestOps API token
ALLURE_PROJECT_ID Numeric TestOps project ID
ALLURE_RESULTS Path to the directory that receives Allure result files
ALLURE_LAUNCH_NAME Optional launch name
ALLURE_LAUNCH_TAGS Optional comma-separated launch tags
One-time local upload with command-line flags

For a local verification run, you can pass the same values directly on the command line instead of exporting variables first:

./allurectl upload \
  --endpoint https://testops.example.com \
  --token 55555555-5555-5555-5555-555555555555 \
  --project-id 100 \
  --launch-name "Local verification run" \
  path/to/allure-results

Use this for ad hoc uploads. For repeatable CI or shell workflows, environment variables are easier to audit and reuse.

allurectl watch

Use watch when the tests are still running and you want allurectl to stream result files as they appear.

This is the preferred mode for CI systems because it reduces the delay between test execution and launch visibility in TestOps.

Example:

export ALLURE_ENDPOINT=https://testops.example.com
export ALLURE_TOKEN=55555555-5555-5555-5555-555555555555
export ALLURE_PROJECT_ID=100
export ALLURE_RESULTS=build/allure-results
export ALLURE_LAUNCH_NAME="Nightly API tests"

./allurectl watch -- ./gradlew clean test

Important behavior:

  • the command after -- is your normal test command;
  • allurectl watches the results path and uploads files as they appear;
  • if TestOps started the job run, allurectl uses the injected job-run context instead of creating a new standalone launch.

If the actual test execution happens inside another Docker container, remote shell, or nested runner, make sure the same ALLURE_* variables and the results directory are visible inside that execution boundary as well.

Pass pipeline context to remote execution

If the tests must run outside the parent CI job, for example in a Docker container, remote VM, bare-metal runner, or downstream pipeline, pass the encoded TestOps job-run context into that execution boundary before starting allurectl.

In the parent pipeline:

ALLURE_CI_ENV=$(allurectl ci env --encode)

Pass ALLURE_CI_ENV to the environment where the tests will actually run, then start allurectl there as usual:

./allurectl watch -- ./run-tests.sh

This keeps the upload attached to the job run that triggered the external execution instead of creating an unrelated standalone launch.

allurectl upload

Use upload when the tests already finished and the result files are complete before the command starts.

Example:

export ALLURE_ENDPOINT=https://testops.example.com
export ALLURE_TOKEN=55555555-5555-5555-5555-555555555555
export ALLURE_PROJECT_ID=100
export ALLURE_LAUNCH_NAME="Local verification run"

./allurectl upload path/to/allure-results

upload is useful for local verification workflows or for CI paths where streaming is not appropriate. For most CI systems, prefer watch.

Do not treat upload as a background helper that runs before the results are complete. It should start only after the result files are already written.

Test the connection before wiring a pipeline

Use auth login only as a connectivity check:

export ALLURE_ENDPOINT=https://testops.example.com
export ALLURE_TOKEN=55555555-5555-5555-5555-555555555555

./allurectl auth login

This is useful from a workstation or a CI runner while you validate endpoint reachability and token validity. It is not the upload step for the real pipeline.

Tests rerun and selective run with allurectl

Selective execution depends on a testplan.json file that identifies which tests the runtime should execute.

In the current TestOps-driven flow:

  1. TestOps starts a job run and provides the job-run context.
  2. allurectl prepares the testplan.json file and exposes the related test plan path to the runtime.
  3. The Allure adapter for the test framework reads that plan and runs only the selected tests.

In other words, current TestOps-triggered selective runs do not require you to manually generate testplan.json in the pipeline. Keep the legacy manual path only if your existing automation still depends on it.

testplan.json structure

If you need to validate adapter behavior locally, you can still create a plan file manually and point the runtime at it.

Example:

{
  "version": "1.0",
  "tests": [
    {
      "id": "10",
      "selector": "io.qameta.allure.examples.junit4.AllureSimpleTest.allureSimpleTest"
    },
    {
      "id": "11",
      "selector": "io.qameta.allure.examples.junit4.AllureParameterizedTest.allureParameterizedTest[First Name]"
    }
  ]
}

Where:

  • id is the Allure ID from TestOps;
  • selector is the test-framework-specific selector used by the adapter.

If your CI starts every test even when TestOps prepared a test plan, the most likely causes are:

  • the test framework adapter does not consume the TestOps plan;
  • the runtime is not reading the plan path;
  • the pipeline is bypassing the intended allurectl execution flow.
Validate selective execution locally

You can still create a local testplan.json, point ALLURE_TESTPLAN_PATH to it, and run the tests on a workstation or an isolated runner to prove the adapter respects the plan before you debug the full CI path.

Reuse launch metadata after upload

In CI-aware mode, allurectl can expose the created job-run and launch values to later pipeline steps.

After watch or upload finishes:

export $(allurectl job-run env)

This makes values such as ALLURE_JOB_RUN_URL and ALLURE_LAUNCH_URL available for follow-up notifications or pipeline summaries.

Use ALLURE_JOB_RUN_URL when you need the exact job-run URL created inside the launch. This is the safer link when one launch may contain multiple job runs.

Cookbook

Run tests even when TestOps is unreachable

By default, allurectl fails the pipeline if it cannot connect to TestOps. Use --silent to let the tests run anyway without uploading results.

./allurectl watch --silent -- <your test command>

allurectl logs a warning and proceeds with the test command. No results are uploaded.

Available starting from allurectl release 2.15.0.

Skip result files that exceed the size limit

TestOps does not process *-result.json files larger than 2,000,000 bytes. Use --skip-too-big to skip them at upload time and avoid silent failures.

./allurectl watch --skip-too-big -- <your test command>

Files that exceed the limit are logged as warnings and not uploaded.

Available starting from allurectl release 2.15.0.

Skip attachments for passed tests

Use --ignore-passed-test-attachments to avoid uploading attachments from passing tests. This reduces storage usage and speeds up upload.

./allurectl watch --ignore-passed-test-attachments -- <your test command>
./allurectl upload --ignore-passed-test-attachments ${ALLURE_RESULTS}

Attachments in fixture setup and teardown blocks are uploaded regardless of this flag.

Available starting from allurectl release 2.9.0.

To skip files by name pattern, use --exclude-files with a Go-flavored regular expression:

./allurectl watch --exclude-files '/*-container.json' -- <your test command>

In CI mode, after watch completes:

allurectl launch add-issue --current-launch \
  --integration-id <integration_id> \
  --issue-keys AE-1,AE-2

In non-CI mode, provide the launch ID explicitly:

allurectl launch add-issue --launch-id <launch_id> \
  --integration-id <integration_id> \
  --issue-keys AE-1,AE-2

The integration_id is available in the Allure TestOps integration settings.

Available starting from allurectl release 2.2.0.

Run a TestOps test plan from the pipeline

To execute only the test cases from a specific TestOps test plan, generate testplan.json before starting the tests:

export ALLURE_TESTPLAN_PATH="testplan.json"
./allurectl test-case plan -q "testPlan=<plan_id>" --output-file ${ALLURE_TESTPLAN_PATH}
./allurectl watch -- <your test command>

Replace <plan_id> with the numeric ID of the test plan in TestOps.

Read allurectl output

After upload completes, allurectl prints a full summary. Example:

Allure TestOps Client v2.15.1
Project [5] with name [my project]
Creating new launch with name [nightly 2024-01-15 113340]
Launch [34] with name [nightly 2024-01-15 113340]
Session [35] started
Report link: https://testops.example.com/launch/34
...
Total files indexed: 29796 || Finished files: 28968 || Orphan Files: 828

+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+
| INDEXING: |                         Total=29796                         | Completed=28968 |              |                |
+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+
|   STATS:  |          type           |      count      |              |                |
+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+
|           |        allure.attach    |      19123      |              |                |
|           |        allure.result    |      6074       |              |                |
|           |       allure.container  |      3610       |              |                |
|           |           unknown       |       989       |              |                |
+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+
|  TIMINGS: |          Duration=6m26s |  Min=325ms      | Avg=2m50s    | Max=6m26s      |
+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+
|   SKIPS:  |                            Reason                           |      Count      |              |                |
+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+
|           | can't find *-result.json or *-container.json for attachment |       828       |              |                |
+-----------+-------------------------------------------------------------+-----------------+--------------+----------------+

+----------+--------------------+------------------+---------------------+--------------------+---------------+
|  FILES:  | TotalBatches=3645  | TotalFiles=28968 | UploadedFiles=28968 | TotalSize=7.170 GB | ErrorsCount=0 |
+----------+--------------------+------------------+---------------------+--------------------+---------------+

Watcher finished in [6m28s]
You can find report here: https://testops.example.com/launch/34

Key fields:

  • Completed — files successfully processed by TestOps. If this is zero and ErrorsCount is non-zero, the results directory was already populated before allurectl watch started — use allurectl upload instead.
  • Orphan Files / SKIPS — attachments with no matching *-result.json or *-container.json. These are not stored and are deleted when the launch closes. A non-zero count at the end of the run may indicate the wrong results path.
  • unknown — files in the results directory that do not follow the Allure naming convention; likely orphans or garbage.
  • ErrorsCount — upload errors. Any non-zero value warrants investigation with --log debug.

Troubleshooting

Enable debug logging

Use the --log switch to collect detailed upload logs. The switch must be placed before the watch or upload command — if added after, it is ignored.

./allurectl --log debug watch -- <your test command>
./allurectl --log debug upload ${ALLURE_RESULTS}

Available log levels from least to most verbose: fatal, error, warn, info, debug, trace.

For each uploaded batch, allurectl outputs details on the upload process. Debug level includes the full HTTP exchange with the TestOps API, which helps identify authentication failures, incorrect endpoints, and upload errors.

Detailed debug logging is available starting from allurectl release 2.11.0.

No results arrive in TestOps

Check these points first:

  • ALLURE_ENDPOINT, ALLURE_TOKEN, and ALLURE_PROJECT_ID point to the expected TestOps project;
  • ALLURE_RESULTS points to the directory where the test framework actually writes results;
  • the command is using watch or upload in the intended place in the pipeline.

A TestOps-triggered run creates a new launch instead of using the job run

This usually means the TestOps service context did not reach allurectl. Confirm that the CI integration passes the job-run variables through to the environment where allurectl runs.

Selective execution is ignored

If the runtime executes every test instead of following the plan, verify the adapter integration for the test framework and confirm that the plan path is available to the test process.

Tests produce too much stdout output

When tests write a large amount of data to stdout (for example, trace-level logging), allurectl watch can fail with:

Error: failed to scan err pipe: bufio.Scanner: token too long

This is a pipe buffer limitation. Two options:

  1. Reduce stdout output in the tests — keep only what is needed for troubleshooting rather than tracing everything.
  2. Increase the buffer size with --stdout-max-buff-size. The default is 1048576 bytes; increase gradually rather than setting the maximum.
./allurectl watch --stdout-max-buff-size 2097152 -- <your test command>

For the full CLI surface, use ./allurectl watch --help or ./allurectl upload --help.

© Qameta Software Inc. All rights reserved.