---
title: History files
description: Explore the structure and use of history files in Allure for tracking test results, statuses, and trends like retries, durations, and defects.
---

# History files

Warning:
This page describes a data format used by Allure. Understanding this format is **not necessary** for using Allure in your project. For a more high-level description of working with history, see [Tests history](/docs/history-and-retries/#tests-history).

The `history` directory in Allure Report 2 and the history JSONL file, which replaced it in Allure Report 3, are used for transferring simplified information between consecutive test reports.

Historical data populates the History tab in the test details and [various charts](/docs/visual-analytics/).

## Allure Report 3

Allure report 3 stores all historical data in a single JSONL file, its location determined by the `historyPath` [configuration parameter](/docs/v3/configure/#_3-history-options).

### 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

Example:

```jsonl
{"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":""}
```

Each history entry contains:

- `uuid` (string) — unique ID for this report run.
- `name` (string) — report name.
- `timestamp` (integer) — when this run happened, in the UNIX timestamp format.
- `knownTestCaseIds` (array of strings) — array of test case IDs.
- `testResults` (object) — object keyed by `historyId` containing test results.
- `url` (string) — remote URL (e.g., CI job URL).

Each test result in the `testResults` object contains:

- `id` (string) — the unique identifier of this history item.
- `name` (string) — the title of the test. Copied from [`name`](/docs/how-it-works-test-result-file/#name-string) in the test result file.
- `fullName` (string) — a unique identifier based on the file name and the test name. Copied from [`fullName`](/docs/how-it-works-test-identifiers/#fullname) in the test result file.
- `environment` (string) — environment name. Set by matching labels via rules defined in the [configuration file](/docs/v3/configure/#_6-environments).
- `status` (string) — the status with which the test or step finished. Copied from [`status`](/docs/how-it-works-test-result-file/#status-string) in the test result file.
- `start` (integer) — the time when the execution started, in the UNIX timestamp format. Copied from [`start`](/docs/how-it-works-test-result-file/#start-integer) in the test result file.
- `stop` (integer) — the time when the execution finished, in the UNIX timestamp format. Copied from [`stop`](/docs/how-it-works-test-result-file/#stop-integer) in the test result file.
- `duration` (integer) — the difference between the `start` and `stop` values.
- `labels` (array) — array of test labels. Copied from [`labels`](/docs/how-it-works-test-result-file/#labels-array) in the test result file.
- `url` (string) — currently unused.
- `historyId` (string) — the [`historyId`](/docs/how-it-works-test-identifiers/#historyid) for this history item.
- `reportLinks` (array) — currently unused.

Failed tests also contain the following fields populated with error data copied from [`statusDetails`](/docs/how-it-works-test-result-file/#statusdetails-object) in the test result file:

- `message` (string) — a brief description of why the test failed.
- `trace` (string) — the complete stack trace showing where in the code the failure occurred.

Single test result object example:

```json
{
  "9b448b5eff623519556020f329494163.d41d8cd98f00b204e9800998ecf8427e": {
    "id": "74364e3f7162027e8e10fe7f3af56b5e",
    "name": "Creating new issue authorized user",
    "fullName": "io.qameta.allure.IssuesWebTest.shouldCreateIssue",
    "environment": "default",
    "status": "passed",
    "start": 1748616059263,
    "stop": 1748616060376,
    "duration": 1113,
    "labels": [
      {
        "name": "framework",
        "value": "junit-platform"
      },
      {
        "name": "language",
        "value": "java"
      },
      {
        "name": "package",
        "value": "io.qameta.allure.IssuesWebTest"
      },
      {
        "name": "testClass",
        "value": "io.qameta.allure.IssuesWebTest"
      },
      {
        "name": "testMethod",
        "value": "shouldCreateIssue"
      },
      {
        "name": "suite",
        "value": "io.qameta.allure.IssuesWebTest"
      }
    ],
    "url": "",
    "historyId": "9b448b5eff623519556020f329494163.d41d8cd98f00b204e9800998ecf8427e",
    "reportLinks": []
  }
}
```

### Configuration

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

## Allure Report 2

Allure Report 2 generates its `history` directory during test report generation. It can then be copied to the test results directory for the new report, either manually or by a CI integration plugin.

The directory contains the following files:

- [history.json](#historyjson)
- [history-trend.json](#history-trendjson)
- [duration-trend.json](#duration-trendjson)
- [retry-trend.json](#retry-trendjson)
- [categories-trend.json](#categories-trendjson)

### history.json

The `history/history.json` file stores general information about runs of each test.

In the root JSON object in the file, each key is some test's [`historyId`](/docs/how-it-works-test-identifiers/#historyid). Each value is an object containing:

- `statistic` — the statistics related to the test (used for the [Test statuses chart](/docs/visual-analytics/#test-statuses-chart)).
- `items` — information about specific runs of the test (used for the History tab in the test details).

Example:

```json
{
  "4da3226ec9761b158ba5f826fc8f8289": {
    "statistic": {
      "failed": 1,
      "broken": 0,
      "skipped": 0,
      "passed": 0,
      "unknown": 0,
      "total": 1
    },
    "items": [
      {
        "uid": "74556baed1daf783",
        "reportUrl": "https://reports.example.com/1234",
        "status": "failed",
        "statusDetails": "AssertionError: Some fail reason\nassert False",
        "time": {
          "start": 1682358404995,
          "stop": 1682358404995,
          "duration": 0
        }
      }
    ]
  }
}
```

In the `statistic` object, there is a key corresponding to each possible [test status](/docs/test-statuses/). The value for each of these keys represents the number of times the test got this status. Additionally, there is the `total` key, with the value representing the total number of reports that include this test.

The `items` array represents the test's data from different test reports. Each object in the array has the following properties:

- `uid` (string) — the unique identifier of this history item.
- `reportUrl` (string) — the URL of the test report from which this data is extracted.
- `status` (string) — the status with which the test or step finished. Copied from [`status`](/docs/how-it-works-test-result-file/#status-string) in the test result file.
- `statusDetails` (string) — the short text message with which the test finished. Copied from [`statusDetails.message`](/docs/how-it-works-test-result-file/#statusdetails-object) in the test result file.
- `time` (object):
  - `start` (integer) — the time when the execution started, in the UNIX timestamp format. Copied from [`start`](/docs/how-it-works-test-result-file/#start-integer) in the test result file.
  - `stop` (integer) — the time when the execution finished, in the UNIX timestamp format. Copied from [`stop`](/docs/how-it-works-test-result-file/#stop-integer) in the test result file.
  - `duration` (integer) — the difference in seconds between the `start` and `stop` values.

### history-trend.json

The `history/history-trend.json` file stores data for the [Trend chart](/docs/visual-analytics/#trend-charts).

Example:

```json
[
  {
    "buildOrder": 1234,
    "reportName": "Report #1234",
    "reportUrl": "https://reports.example.com/1234",
    "data": {
      "failed": 0,
      "broken": 0,
      "passed": 32,
      "skipped": 0,
      "unknown": 0,
      "total": 32
    }
  }
]
```

Each object in the array has the following properties:

- `buildOrder` (integer) — the identifier provided by the build's [`executor.json`](/docs/how-it-works-executor-file/).
- `reportUrl` (string) — the URL of the test report from which the data is extracted.
- `reportName` (string) — the title of the report from which the data is extracted.
- `data` (object) — in this object, there is a key corresponding to each category (see [Categories](/docs/categories/)). The value for each of these keys represents the number of tests in this category. The value for the `total` key indicates the total number of tests.

### duration-trend.json

The `history/duration-trend.json` file stores data for the Duration trend chart, see [Trend charts](/docs/visual-analytics/#trend-charts).

Example:

```json
[
  {
    "buildOrder": 1234,
    "reportName": "Report #1234",
    "reportUrl": "https://reports.example.com/1234",
    "data": {
      "duration": 78
    }
  }
]
```

Each object in the array has the following properties:

- `buildOrder` (integer) — the identifier provided by the build's [`executor.json`](/docs/how-it-works-executor-file/).
- `reportUrl` (string) — the URL of the test report from which the data is extracted.
- `reportName` (string) — the title of the report from which the data is extracted.
- `data` (object):
  - `duration` (integer) — number of seconds it took to run all the tests.

### retry-trend.json

The `history/retries-trend.json` file stores data for the Retries trend chart, see [Trend charts](/docs/visual-analytics/#trend-charts).

Example:

```json
[
  {
    "buildOrder": 1234,
    "reportName": "Report #1234",
    "reportUrl": "https://reports.example.com/1234",
    "data": {
      "run": 39,
      "retry": 15
    }
  }
]
```

Each object in the array has the following properties:

- `buildOrder` (integer) — the identifier provided by the build's [`executor.json`](/docs/how-it-works-executor-file/).
- `reportUrl` (string) — the URL of the test report from which the data is extracted.
- `reportName` (string) — the title of the report from which the data is extracted.
- `data` (object):
  - `run` (integer) — number of test runs that did not cause a retry.
  - `retry` (integer) — number of test runs that caused a retry.

### categories-trend.json

The `history/categories-trend.json` file stores data for the Categories trend chart, see [Trend charts](/docs/visual-analytics/#trend-charts).

Example:

```json
[
  {
    "buildOrder": 1234,
    "reportName": "Report #1234",
    "reportUrl": "https://reports.example.com/1234",
    "data": {
      "Product defects": 2,
      "Test defects": 1
    }
  }
]
```

Each object in the array has the following properties:

- `buildOrder` (integer) — the identifier provided by the build's [`executor.json`](/docs/how-it-works-executor-file/).
- `reportUrl` (string) — the URL of the test report from which the data is extracted.
- `reportName` (string) — the title of the report from which the data is extracted.
- `data` (object) — in this object, there is a key corresponding to each category (see [Categories](/docs/categories/)). The value for each of these keys represents the number of tests in this category.