Configure Allure Report 3

Allure Report 3 uses a single configuration file to manage all your report settings. You can create this file in either dynamic (JavaScript) or static (JSON/YAML) format. Dynamic configs support executable code, imports, and conditional logic, while static configs provide a simpler format with fixed values.

You can load configuration values from environment variables and override them via CLI command options, giving you flexibility in how you manage settings across different environments and workflows.

Advanced Allure 3 features are implemented as a system of plugins. You can configure all plugins in the same configuration file.

What This Document Covers

• Configuration file structure and syntax
• All primary configuration options
• Adding plugins and configuring multiple reports types
• Advanced features like history tracking and known issues
• CLI commands and overrides

1. Configuration File Basics

File Name and Location

Allure CLI looks for configuration files in the current working directory, in the following order (first file discovered gets parsed for configuration parameters):

• allurerc.js
• allurerc.mjs
• allurerc.cjs
• allurerc.json
• allurerc.yaml
• allurerc.yml

File Format and Syntax

Allure 3 supports both dynamic configs (.mjs, .cjs, .js) and static configs (.json, .yml, .yaml).

Static configs have limited functionality (no imports, no reading from environment variables, no executable code) but work with a global install of Allure Report 3.

Dynamic config files are written in JavaScript. They require Allure 3 to be locally installed in your project and you can use the following in them:

• Environment variables
• Conditional logic
• Computed values
• Imported utilities

Dynamic and Static Configuration File Examples

allurerc.mjs

import { defineConfig } from "allure";

export default defineConfig({
  name: "Allure Report",
  output: "./allure-report",
  historyPath: "./history.jsonl",
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
        fastFail: true,
      },
    ],
  },
  plugins: {
    awesome: {
      options: {
        reportName: "HelloWorld",
        singleFile: false,
        reportLanguage: "en",
        open: false,
        charts: chartLayout,
        publish: true,
      },
    },
    allure2: {
      options: {
        reportName: "HelloWorld",
        singleFile: false,
        reportLanguage: "en",
      },
    },
    classic: {
      options: {
        reportName: "HelloWorld",
        singleFile: false,
        reportLanguage: "en",
      },
    },
    dashboard: {
      options: {
        singleFile: false,
        reportName: "HelloWorld-Dashboard",
        reportLanguage: "en",
        layout: defaultChartsConfig,
      },
    },
    csv: {
      options: {
        fileName: "allure-report.csv",
      },
    },
    log: {
      options: {
        groupBy: "none",
      },
    },
  },
  variables: {
    env_variable: "unknown",
  },
  environments: {
    foo: {
      variables: {
        env_variable: "foo",
        env_specific_variable: "foo",
      },
      matcher: ({ labels }) => labels.some(({ name, value }) => name === "env" && value === "foo"),
    },
    bar: {
      variables: {
        env_variable: "bar",
        env_specific_variable: "bar",
      },
      matcher: ({ labels }) => labels.some(({ name, value }) => name === "env" && value === "bar"),
    },
  },
});

allurerc.json

{
  "name": "Allure Report",
  "output": "./allure-report",
  "historyPath": "./history.jsonl",
  "qualityGate": {
    "rules": [
      {
        "maxFailures": 5,
        "fastFail": true
      }
    ]
  },
  "plugins": {
    "awesome": {
      "options": {
        "reportName": "HelloWorld",
        "singleFile": false,
        "reportLanguage": "en",
        "open": false,
        "publish": true
      }
    },
    "allure2": {
      "options": {
        "reportName": "HelloWorld",
        "singleFile": false,
        "reportLanguage": "en"
      }
    },
    "classic": {
      "options": {
        "reportName": "HelloWorld",
        "singleFile": false,
        "reportLanguage": "en"
      }
    },
    "awesome": {
      "options": {
        "reportName": "HelloWorld",
        "singleFile": false,
        "reportLanguage": "en",
        "open": false,
        "publish": true
      }
    },
    "dashboard": {
      "options": {
        "singleFile": false,
        "reportName": "HelloWorld-Dashboard",
        "reportLanguage": "en"
      }
    },
    "csv": {
      "options": {
        "fileName": "allure-report.csv"
      }
    },
    "log": {
      "options": {
        "groupBy": "none"
      }
    }
  },
  "variables": {
    "env_variable": "unknown"
  }
}

allurerc.yaml

name: Allure Report
output: ./allure-report
historyPath: ./history.jsonl
qualityGate:
  rules:
    - maxFailures: 5
      fastFail: true
plugins:
  allure2:
    options:
      reportName: HelloWorld
      singleFile: false
      reportLanguage: en
  classic:
    options:
      reportName: HelloWorld
      singleFile: false
      reportLanguage: en
  awesome:
    options:
      reportName: HelloWorld
      singleFile: false
      reportLanguage: en
      open: false
      publish: true
  dashboard:
    options:
      singleFile: false
      reportName: HelloWorld-Dashboard
      reportLanguage: en
  csv:
    options:
      fileName: allure-report.csv
  log:
    options:
      groupBy: none
variables:
  env_variable: unknown

Dynamic Config File Capabilites and Prerequisites

For Node.js Projects

Add Allure as a development dependency to your project:

cd your-project
npm install -D allure

Then, wrap the configuration object with the defineConfig function:

import { defineConfig } from "allure";

export default defineConfig({
  name: "My Allure Report",
  // ... configuration
});

For Other Types of Projects

You can use a global installation of Allure Report and just export the configuration object directly:

export default {
  name: "My Allure Report",
  // ... configuration
};

This way, however, you won't get type hints.

You can get around that limitation by initializing a dummy Node.js project and installing Allure to it:

npm init --yes
npm install -D allure

Then, wrap the configuration object in the defineConfig function, just as you would for any Node.js project (see the section above).

Reading Environment Variables

Since dynamic config files are executable JavaScript, you can use:

import { env } from "node:process";

export default {
  name: env.REPORT_NAME || "Default Report",
  output: env.CI ? "./ci-reports" : "./local-reports",
};

Importing Code

When using dymanic files you can offload some executable logic to other JavaScript files and then import it to your config from them.

You can also import code form other Node.js modules, including Allure 3 plugins.

Default Top-Level Values Reference

Option	Default Value
name	"Allure Report"
output	"./allure-report"
historyPath	undefined
knownIssuesPath	"./allure/known.json"
appendHistory	true
variables	{}
environments	{}
defaultLabels	{}
plugins	{ awesome: { options: {} } }

2. Basic Configuration Options

name

• Type: string
• Default: "Allure Report"
• Description: Display name for the report

{
  name: "My Test Suite Report";
}

output

• Type: string
• Default: "./allure-report"
• Description: Directory where the report will be generated

{
  output: "./reports/allure";
}

3. History Options

historyPath

• Type: string
• Default: undefined
• Description: Path to the history file that tracks test results across multiple runs
• Format: JSONL (JSON Lines) - each line contains data from one complete test run
• Used for:
  • Trend charts showing test behavior over time
  • Flaky test detection
  • Historical comparisons

{
  historyPath: "./test-history/allure-history.jsonl";
}

appendHistory

• Type: boolean
• Default: true
• Description: Controls history accumulation behavior

{
  appendHistory: true;
}

File Structure: See History File section for details.

4. Known Issues Options

knownIssuesPath

• Type: string
• Default: "./allure/known.json"
• Description: Path to JSON file containing known test failures

{
  knownIssuesPath: "./config/known.json";
}

File Structure: See Known Issues Management section for details.

5. Variables and Labels

variables

Display custom key-value metadata at the top of the report.

• Type: Record<string, string>
• Default: {}
• Where shown: Top of report in awesome plugin
• Purpose: Display build/run metadata

Example

{
  variables: {
    "App Version": "2.5.1",
    "Test Suite": "Regression v1.2",
    "Launch Date": "2025-10-20",
    "Build Number": "#1234",
    "Environment": "Staging"
  }
}

defaultLabels

Apply default labels to tests.

• Type: Record<string, string | string[]>
• Default: {}
• Behavior: Non-overriding - only applies if test doesn't have that label
• Purpose: Provide fallback values for missing labels

Example

{
  defaultLabels: {
    "severity": "normal",
    "owner": "unassigned",
    "layer": "unknown",
    "tags": ["needs-review"]
  }
}

How It Works

• Test with severity: "critical" → keeps "critical" (not overridden)
• Test without severity → gets "normal" from defaults
• Test without tags → gets ["needs-review"]
• Test with tags: ["smoke"] → keeps ["smoke"]

Label Values

Single value:

"severity": "critical"

Multiple values (array):

"tags": ["smoke", "regression", "api"]

6. Environments

Group and categorize test results by environment with custom matching logic.

• Type: Record<string, EnvironmentDescriptor>
• Default: {}
• Purpose: Create an "Environments" menu in reports and split test result tree into environment-based groups, which you can switch between using that menu.

Structure

{
  environments: {
    "environment-name": {
      matcher: ({ labels }) => boolean,    // Required
      variables?: Record<string, string>   // Optional
    }
  }
}

Matcher Function

Receives test labels and returns true if the test belongs to this environment. Requires dynamic config to work.

Payload structure:

{
  labels: [
    { name: "os", value: "Windows" },
    { name: "browser", value: "Chrome" },
    // ... more labels
  ];
}

Note: these labels should be set in the tests as there are no default values for environment labels.

Example - OS-based Environments

{
  environments: {
    windows: {
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "os" && value === "Windows"),
      variables: {
        "OS": "Windows 11",
        "Architecture": "x64"
      }
    },
    macos: {
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "os" && value === "macOS"),
      variables: {
        "OS": "macOS Sonoma",
        "Architecture": "arm64"
      }
    },
    linux: {
      matcher: ({ labels }) =>
        labels.find(({ name, value }) => name === "os" && value === "Linux"),
      variables: {
        "OS": "Ubuntu 22.04",
        "Architecture": "x64"
      }
    }
  }
}

Example - Deployment Environments

{
  environments: {
    staging: {
      matcher: ({ labels }) =>
        labels.find(l => l.name === "env" && l.value === "staging"),
      variables: {
        "Server": "staging.example.com",
        "Database": "staging-db"
      }
    },
    production: {
      matcher: ({ labels }) =>
        labels.find(l => l.name === "env" && l.value === "production"),
      variables: {
        "Server": "api.example.com",
        "Database": "prod-db-primary"
      }
    }
  }
}

Environment Variables

Optional environment-specific variables override or extend global variables when viewing that environment.

Merge behavior:

1. Global variables shown in all views
2. Environment-specific variables override/add to globals when that environment is selected

Use Cases

• Group tests by OS (Windows/macOS/Linux)
• Group by browser (Chrome/Firefox/Safari)
• Group by deployment environment (staging/production)
• Group by any custom label-based criteria

7. History File

History File Format

File: JSONL (JSON Lines) format - one JSON object per line

Location: Configured via historyPath (default: undefined)

Structure: Each line represents one complete test run

{"uuid":"abc-123","name":"Allure Report","timestamp":1697020800000,"knownTestCaseIds":["tc1","tc2"],"testResults":{...},"metrics":{},"url":""}
{"uuid":"def-456","name":"Allure Report","timestamp":1697107200000,"knownTestCaseIds":["tc1","tc2","tc3"],"testResults":{...},"metrics":{},"url":""}

What's Tracked

Each history entry contains:

• uuid - Unique ID for this report run
• name - Report name
• timestamp - When this run happened
• knownTestCaseIds - Array of test case IDs
• testResults - Object keyed by historyId containing test results
• url - Remote URL (e.g., CI job URL)

How History is Used

• Trend charts - Status, duration over time
• Flaky test detection - Inconsistent pass/fail patterns
• New/removed tests - Compare test case IDs across runs
• Historical context - Previous error messages, durations

Configuration

{
  historyPath: "./.allure/history.jsonl",
  appendHistory: true
}

8. Known Issues Management

Track known test failures and link them to bug tracker tickets.

Configuration

{
  knownIssuesPath: "./allure/known.json";
}

File Structure

File: JSON array of known issue objects

[
  {
    "historyId": "a3f5e9b2c1d4f8a7b6e5c4d3a2f1e0b9",
    "issues": [
      {
        "name": "JIRA-1234",
        "url": "https://jira.example.com/browse/JIRA-1234"
      }
    ],
    "comment": "Known flaky test due to database connection issues",
    "error": {
      "message": "Connection timeout"
    }
  }
]

Fields

historyId (required)

• Type: string
• Description: The test's history ID (internal identifier unique to each test)
• Format: MD5 hash of test metadata (name, path, parameters)
• How to get: From raw test result files

issues (optional)

• Type: Array of link objects
• Description: Links to bug tracker tickets

{
  "name": "JIRA-1234",
  "url": "https://jira.example.com/browse/JIRA-1234"
}

comment (optional)

• Type: string
• Description: Human-readable explanation of the known issue

error (optional)

• Type: Error object
• Description: Expected error pattern for this known issue

{
  "message": "Connection timeout after 5000ms",
  "trace": "..."
}

Creating Known Issues File

Automated (Recommended)

Use the CLI command to auto-generate from failed tests:

allure known-issue ./allure-results

What it does:

1. Finds all failed/broken tests
2. Extracts their historyId
3. Extracts any "issue" type links from test metadata
4. Creates known.json with standard comment

Manual

1. Find the historyId from raw test result files
2. Create or edit known.json
3. Add entry with desired fields

How It Works

1. Test runs and has a historyId
2. Allure checks if this historyId exists in known issues
3. If match found:
   • Test marked as "known failure"
   • Issue links displayed
   • Comment shown
   • May affect Quality Gate evaluation

Use Cases

• Track known flaky tests
• Link failures to bug tracker
• Provide context to team members
• Separate "new failures" from "known issues"
• Document expected failures

9. Plugin Configuration

Plugin System Overview

Allure 3 uses a plugin-based architecture. Each plugin generates a specific type of report or provides additional functionality.

Available Official Plugins:

• awesome - Modern UI (recommended)
• classic - Classic/Allure 2-style UI
• allure2 - Allure 2 compatibility
• dashboard - Dashboard view with charts
• log - Console log output
• csv - CSV export
• slack - Slack integration
• testplan - Test plan generation
• jira - Jira integration

You can find the official plugins code in the Allure 3 repository.

Basic Plugin Configuration

To enable a plugin in your project, install the plugin package:

npm add @allurereport/plugin-name

And add it to the plugins section of the config:

{
  plugins: {
    "name": {
      options: {
        // plugin-specific options
      }
    }
  }
}

Plugin Configuration Properties

import (optional)

Custom module path for the plugin

{
  plugins: {
    "my-custom-id": {
      import: "@allurereport/plugin-awesome",
      options: {}
    }
  }
}

Use case: Running multiple instances of the same plugin with different configurations

enabled (optional)

Enable or disable the plugin

• Type: boolean
• Default: true

{
  plugins: {
    awesome: {
      enabled: false,  // Disable this plugin
      options: {}
    }
  }
}

options (optional)

Plugin-specific configuration object

• Type: Record<string, any>
• Default: {}

{
  plugins: {
    awesome: {
      options: {
        singleFile: true,
        reportLanguage: "en"
      }
    }
  }
}

Multiple Reports

You can generate multiple reports by configuring multiple plugins:

{
  plugins: {
    "awesome-framework": {
      import: "@allurereport/plugin-awesome",
      options: {
        reportName: "Framework View",
        groupBy: ["framework", "language"]
      }
    },
    "awesome-package": {
      import: "@allurereport/plugin-awesome",
      options: {
        reportName: "Package View",
        groupBy: ["package", "suite"]
      }
    },
    dashboard: {
      options: {
        reportName: "Dashboard"
      }
    }
  }
}

Default Plugin

If no plugins are specified, Allure uses the awesome plugin by default:

// These are equivalent:
export default { name: "Report" }

export default {
  name: "Report",
  plugins: {
    awesome: { options: {} }
  }
}

10. Plugin Options

Awesome Plugin

Recommended modern UI for Allure reports.

Common Options

reportName (string)

• Overrides the top-level name for this report

singleFile (boolean, default: false)

• Generate report as a single standalone HTML file
• true: Single HTML file
• false: Multiple files

reportLanguage (default: "en")

• Sets the UI language

groupBy (string[])

• Defines test result hierarchy organization
• Array of label names

Common patterns:

// BDD-style hierarchy
groupBy: ["epic", "feature", "story"];

// Suite-based hierarchy
groupBy: ["parentSuite", "suite", "subSuite"];

// Package-based hierarchy
groupBy: ["package", "class", "method"];

// Module-based
groupBy: ["module", "parentSuite", "suite", "subSuite"];

// Custom hierarchy
groupBy: ["framework", "language", "package"];

charts (ChartOptions[])

• Chart/widget configuration
• See Charts Configuration Reference for details

Example Configuration

{
  plugins: {
    awesome: {
      options: {
        singleFile: false,
        reportLanguage: "en",
        reportName: "My Awesome Report",
        groupBy: ["epic", "feature", "story"]
      }
    }
  }
}

Complete Options Reference

For all available options including experimental features, see:

• AwesomePluginOptions source code

Dashboard Plugin

Dashboard view with charts and visualizations.

Common Options

reportName (string)

• Dashboard title

singleFile (boolean, default: false)

• Generate as single file

reportLanguage (default: "en")

• UI language

layout (array of widget configurations)

• Array of chart/widget definitions

Widget structure:

{
  type: "pie" | "trend" | "bar" | "treemap" | "heatmap" | "funnel",
  dataType?: string,  // Optional, varies by widget type
  title: string
}

Example Configuration

{
  plugins: {
    dashboard: {
      options: {
        reportName: "Test Dashboard",
        reportLanguage: "en",
        layout: [
          {
            type: "pie",
            title: "Test Status Distribution"
          },
          {
            type: "trend",
            dataType: "status",
            title: "Status Over Time"
          },
          {
            type: "bar",
            dataType: "statusBySeverity",
            title: "Results by Severity"
          }
        ]
      }
    }
  }
}

Complete Options Reference

For all available options, see:

• DashboardPluginOptions source code

Note: Dashboard generates a separate standalone report from awesome/classic plugins.

Classic Plugin

Classic Allure 2-style UI.

Common Options

reportName (string) reportLanguage ("en" | "ru") singleFile (boolean)

Complete Options Reference

For all available options, see:

• ClassicPluginOptions source code

Log Plugin

Filtered console log view of test results.

Example Configuration

{
  plugins: {
    log: {
      options: {
        groupBy: "none",
        filter: ({ status }) => status === "failed" || status === "broken"
      }
    }
  }
}

Complete Options Reference

For all available options, see:

• LogPluginOptions source code

11. Quality Gate

Controls the process exit code based on test result criteria, allowing test runs to pass or fail based on custom rules.

{
  qualityGate: {
    rules: [
      {
        maxFailures: 5,
      },
    ];
  }
}

Documentation: See Quality Gate Guidefor complete documentation.

Note: This is a complex feature with its own dedicated documentation.

12. CLI Configuration Overrides

Config options can be overridden from the command line:

allure generate \
  --config ./allurerc.mjs \
  --output ./custom-output \
  --name "Overridden Name" \
  --history-path ./custom-history.jsonl

Overridable options:

• --name / --report-name
• --output / -o
• --history-path / -h
• --known-issues
• Plugin-specific options (varies by command)

Plugin-Specific Commands

Generate reports with specific plugins directly:

Awesome Report

allure awesome [options] <directory>

Options:

• --single-file
• --logo
• --theme
• --report-language, --lang
• --group-by, -g

Dashboard

allure dashboard [options] <directory>

Classic Report

allure classic [options] <directory>

CSV Export

allure csv [options] <directory>

Log Output

allure log [options] <directory>

Utility Commands

Known Issues

allure known-issue [--output,-o] <directory>

Generates known issues file from failed tests.

History

allure history [--history-path,-h] [--report-name,--name] <directory>

Generates history to specified folder.

Test Plan

allure testplan [--output,-o] <directory>

Generates testplan.json.

Help

Get detailed help for any command:

allure <command> --help

---

Appendix: Type Definitions Reference

For reference, here are the main TypeScript interfaces that define the configuration structure:

Config Interface

interface Config {
  name?: string;
  output?: string;
  historyPath?: string;
  knownIssuesPath?: string;
  defaultLabels?: DefaultLabelsConfig;
  environments?: EnvironmentsConfig;
  variables?: ReportVariables;
  plugins?: Record<string, PluginDescriptor>;
  appendHistory?: boolean;
  qualityGate?: QualityGateConfig;
  allureService?: {
    url?: string;
    project?: string;
    accessToken?: string;
  };
}

Supporting Types

type DefaultLabelsConfig = Record<string, string | string[]>;

type ReportVariables = Record<string, string>;

type EnvironmentDescriptor = {
  variables?: ReportVariables;
  matcher: (payload: { labels: TestLabel[] }) => boolean;
};

type EnvironmentsConfig = Record<string, EnvironmentDescriptor>;

interface PluginDescriptor {
  import?: string;
  enabled?: boolean;
  options?: Record<string, any>;
}

interface KnownTestFailure {
  historyId: string;
  issues?: TestLink[];
  comment?: string;
  error?: TestError;
}

Additional Resources

• Allure 3 GitHub Repository
• Quality Gate Feature