allure

Allure 3

Allure 3 is the next evolution of the Allure reporting framework, rebuilt from the ground up with a new architecture and expanded capabilities. Unlike its predecessor, Allure 2, this version is developed in TypeScript and introduces a modular plugin system for greater flexibility. A key addition is the Awesome plugin, which delivers an enhanced UI for better report visualization.

The Allure 3 CLI provides a comprehensive suite of commands designed to streamline the generation, serving, and management of test reports.

• Learn more about Allure Report at https://allurereport.org
• Documentation – discover official documentation for Allure Report
• Questions and Support – get help from the team and community
• Official annoucements – be in touch with the latest updates
• General Discussion – engage in casual conversations, share insights and ideas with the community

Key Features

Allure 3 introduces several notable improvements. The framework has been entirely rewritten in TypeScript, making it more extensible and easier to maintain. Its plugin system allows you to customize and extend reporting functionality to fit your specific needs. Configuration has been simplified with a single file managing all report settings, making it more convenient to handle multiple reports.

One of the standout features is real-time reporting, which lets you view live updates during test execution using the watch command. The report interface itself has been redesigned to enhance usability and clarity. Moreover, Allure 3 maintains compatibility with the entire Allure ecosystem, supporting all major test frameworks.

Installation

To install Allure 3 globally, you can use npm. Simply run:

npm install -g allure

However, we recommend using npx for running Allure commands without needing a global installation:

npx allure run -- <test_command>

This approach ensures you always use the latest version without managing global dependencies.

Commands

Running Tests and Generating Reports

Running tests and generating a report with Allure 3 is straightforward. Using the run command, you can execute your test suite and automatically generate a report:

npx allure run -- <test_command>

For example, if you're using npm as your test runner, the command would be:

npx allure run -- npm test

To hide specific labels use --hide-labels option:

npx allure run --hide-labels=owner --hide-labels=tag -- npm test

To successfully generate a report, ensure that your test setup outputs results into an allure-results directory. With allure run / allure agent / empty allure watch, directories named allure-results are discovered dynamically (name-based watcher). With one-shot commands such as allure generate, an empty CLI and unset config.resultsDir default to the ./**/allure-results glob. Quote globs in the shell so they are not expanded early.

You can also set resultsDir in the Allure config (string | string[]) or pass --results-dir on run / agent:

npx allure run --open --results-dir './artifacts/**/allure-results' -- npm test

Repeat --results-dir for multiple patterns. CLI overrides config.resultsDir.

After the tests complete, the report is generated automatically. Existing results from previous runs are ignored, as Allure 3 focuses solely on new data to ensure accurate and up-to-date reporting.

Allure operational messages use scoped prefixes such as [AllureRun]:, [QualityGate]:, and [AllureRerun]:. Set ALLURE_LOG_LEVEL=debug to include details such as selected tests and temporary test plan paths. Allure ignores the generic LOG_LEVEL environment variable. Use --silent to hide the nested test process output while keeping Allure lifecycle messages visible.

Running Tests In Agent Mode

When you need agent-friendly markdown output for review, debugging, or scope validation, use the agent command:

npx allure agent -- <test_command>

For example:

npx allure agent -- npm test

To analyze existing Allure results or dump archives downloaded from CI without rerunning tests, use agent inspect:

npx allure agent inspect path/to/allure-results
npx allure agent inspect --dump allure-results-linux.zip --dump allure-results-macos.zip
npx allure agent inspect --config ./allurerc.mjs --output ./agent-output path/to/allure-results

agent inspect accepts the same result inputs and configuration-style options as allure generate, including result directory globs, --dump, --config, --cwd, --report-name, --history-limit, and --hide-labels. Its --output option writes the agentic output directory.

allure agent and allure agent inspect use --report auto by default. This writes the agent-readable artifacts and, when the stored visible result count is 1000 or fewer, also writes a single-file Awesome report at awesome/index.html inside the agent output directory. Runs above that threshold skip the human report to avoid excessive output, and the status is recorded in index.md, manifest/run.json, and manifest/human-report.json.

Use --report off for agent-only artifacts, --report awesome to force the single-file Awesome report regardless of result count, or --report config to force the configured non-agent report plugins inside the agent output directory. Configured presentation or export plugins such as Dashboard or TestOps are otherwise ignored for agent runs.

If you need the human-readable report from the most recent agent run, first run npx allure agent latest when the output directory is unknown. Then check <output>/manifest/human-report.json; when its status is generated, open <output>/<path> from that manifest, usually <output>/awesome/index.html.

allure agent creates a fresh output directory automatically, accepts compact inline expectations such as --goal, --expect-tests, --expect-test, --expect-label, and --expect-step-containing, and can still load an expectations file with --expectations when needed.

Agents and setup tools can inspect the local structured capability contract without scraping help text:

npx allure agent capabilities --json

After a run, agents can query the output directory without manually reading every manifest:

npx allure agent query --latest summary
npx allure agent query --latest tests --status failed
npx allure agent query --from ./agent-output findings --severity high

Generating Reports Manually

If you already have test results and wish to generate a report manually, use the generate command:

npx allure generate <resultsDir>

By default, this command produces an Allure 3 Awesome report. You can customize output settings, such as the destination directory, through the configuration file. If you prefer a Classic or Allure 2-style report, or need to disable certain plugins, these adjustments can also be made via configuration.

Viewing Reports

To view a previously generated report locally, the open command serves it in your default browser:

npx allure open <reportDir>

When <reportDir> is omitted, Allure 3 uses the configured output directory, falling back to allure-report when no output is configured. To open the Awesome report directly, point to the nested directory:

npx allure open allure-report/awesome

If the provided directory doesn't contain previously generated report, it will be treated as a source of results, and a new report will be generated on the fly and opened in the browser.

Real-time Report Monitoring

When you need to monitor test execution live, the watch command provides dynamic report updates. It continuously monitors the specified results directory for changes and refreshes the report automatically:

npx allure watch <allureResultsDir>

This command is ideal for iterative development and debugging, allowing you to see immediate feedback as you modify and rerun tests. The browser tab updates seamlessly whenever new results are detected.

Command-line Options

The Allure CLI includes several helpful global options. Use --help to explore available commands or get detailed usage information for a specific command:

npx allure run --help
npx allure agent capabilities --json
npx allure agent --help
npx allure watch --help

To check your installed version of Allure 3, use:

npx allure --version

Configuration

Allure 3 uses an allurerc.ts, allurerc.mts, allurerc.cts, allurerc.mjs, or allurerc.js configuration file to manage report settings, including the report name, output directory, and plugin options.

We recommend using the Awesome plugin for the best experience.
Support for Classic and Allure 2-style reports is currently experimental.

Example Configuration File

import { defineConfig } from "allure";

export default defineConfig({
  name: "Allure Report Example",
  output: "./out/allure-report",
  hideLabels: ["owner", /^_/],
  plugins: {
    awesome: {
      options: {
        singleFile: true,
        reportLanguage: "en",
      },
    },
  },
});

In this example, the generated report is named Allure Report Example and saved to the ./out/allure-report directory. The Awesome plugin is enabled with options to produce a single-file HTML report in English.

TypeScript Configuration File

TypeScript configuration files are loaded directly by the Allure CLI, so you don't need to precompile them or install tsx or ts-node.

import type { AllureConfig } from "allure";

export default {
  name: "Allure Report Example",
  output: "./out/allure-report",
} satisfies AllureConfig;

For editor type checking, make sure the allure package is available to your project, for example as a local dev dependency. If you run Allure only as a global CLI, you can still use a TypeScript config without importing from allure.

Configuration Options

The configuration file allows you to fine-tune report generation. Key options include:

• name: Specifies the report’s display name.
• output: Defines the directory where the report will be saved.
• resultsDir (string | string[]): Glob patterns or paths used when reading Allure results directories. For one-shot commands, CLI positionals override this value. For allure run / allure agent, use repeated --results-dir (same override priority). When both CLI and resultsDir are empty, one-shot commands (generate, etc.) use ./**/allure-results, while live commands (run, agent, empty watch) use name-based discovery of directories named allure-results. Quote globs in the shell.
• hideLabels ((string | RegExp)[]): Hides matching labels by name in report data. Currently, only Allure Awesome report respects the option. Labels with names starting with _ are hidden by default.
• plugins: Enables and configures plugins, with each supporting various options.

Awesome Plugin Options

The Awesome plugin offers several customizable options:

• singleFile (boolean): If set to true, generates the report as a single standalone HTML file.

• reportName (string): Overrides the default report name.

• open (boolean): Automatically opens the report after generation if enabled.

• reportLanguage (string): Sets the UI language of the report. Supported languages include:

  az, br, de, en, es, fr, he, ja, kr, nl, pl, ru, sv, tr, zh.

For example, setting "reportLanguage": "fr" will render the report interface in French.

Declarative configuration format

You can also use allurerc.json, allurerc.yaml, or allurerc.yml files as a declarative way to configure Allure 3.

Declarative formats don't support advanced features such as tests filtering or environments. If you need these features, please consider using the allurerc.ts, allurerc.mts, allurerc.cts, allurerc.mjs, or allurerc.js files.

Official CI/CD Integrations

• GitHub Actions
• Azure DevOps