> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hrtk.frotty27.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Export

> JSON and HTML export formats for test results, generated by /hrtk export.

HRTK can export test results to JSON and HTML files for external tooling, CI integration, or historical tracking. Run `/hrtk export` after a test run to write the results to disk. `/hrtk run` also generates both files automatically after each run.

## Generating an Export

```
/hrtk run
/hrtk export
```

Output:

```
--- HRTK Export Complete ---
  JSON: plugins/hrtk-server/results/run_1712345678000.json
  HTML: plugins/hrtk-server/results/run_1712345678000.html
```

Files are written to `<plugin data directory>/results/` with a timestamp-based filename.

## JSON Format

```json theme={null}
{
  "timestamp": 1712345678000,
  "suites": [
    {
      "plugin": "MyMod",
      "suite": "Combat Tests",
      "durationMs": 45,
      "tests": [
        {
          "name": "testSwordDamage",
          "displayName": "Sword deals correct damage",
          "status": "PASSED",
          "durationMs": 3,
          "message": null,
          "tags": ["combat", "melee"]
        },
        {
          "name": "testArrowDamage",
          "displayName": "Arrow deals correct damage",
          "status": "FAILED",
          "durationMs": 5,
          "message": "Expected health below <80.0> but was <95.0>",
          "tags": ["combat", "ranged"]
        }
      ]
    }
  ]
}
```

## Field Reference

### Root Object

| Field       | Type    | Description                                                 |
| ----------- | ------- | ----------------------------------------------------------- |
| `timestamp` | `long`  | Unix timestamp (milliseconds) when the export was generated |
| `suites`    | `array` | List of suite result objects                                |

### Suite Object

| Field        | Type     | Description                                |
| ------------ | -------- | ------------------------------------------ |
| `plugin`     | `string` | Name of the plugin that owns this suite    |
| `suite`      | `string` | Display name of the suite                  |
| `durationMs` | `long`   | Total suite execution time in milliseconds |
| `tests`      | `array`  | List of test result objects                |

### Test Object

| Field         | Type       | Description                                                     |
| ------------- | ---------- | --------------------------------------------------------------- |
| `name`        | `string`   | Method name of the test                                         |
| `displayName` | `string`   | Human-readable display name                                     |
| `status`      | `string`   | One of: `PASSED`, `FAILED`, `ERRORED`, `SKIPPED`, `TIMED_OUT`   |
| `durationMs`  | `long`     | Test execution time in milliseconds                             |
| `message`     | `string?`  | Failure message, error message, or skip reason (null if passed) |
| `tags`        | `string[]` | List of tags applied to this test                               |

## Status Values

| Status      | Description                               |
| ----------- | ----------------------------------------- |
| `PASSED`    | Test completed successfully               |
| `FAILED`    | Assertion failure                         |
| `ERRORED`   | Unexpected exception                      |
| `SKIPPED`   | Test was disabled or precondition not met |
| `TIMED_OUT` | Test exceeded its timeout                 |

## Example: Parsing in Python

```python theme={null}
import json

with open("run_1712345678000.json") as f:
    data = json.load(f)

for suite in data["suites"]:
    print(f"\n{suite['plugin']} / {suite['suite']}")
    for test in suite["tests"]:
        status = test["status"]
        name = test["displayName"]
        ms = test["durationMs"]
        print(f"  [{status}] {name} ({ms}ms)")
        if test["message"]:
            print(f"    {test['message']}")
```

## HTML Report

Every export generates an interactive HTML report alongside the JSON file. The HTML report includes:

* **Color-coded results** - green for passed, red for failed, yellow for skipped
* **Clickable filters** - toggle pass/fail/skip visibility to focus on what matters
* **Light/dark mode** - automatically matches your browser preference, with a manual toggle
* **Self-contained** - the HTML file has no external dependencies, so it works offline

Open the HTML file in any browser to view results. On singleplayer, navigate directly to the results folder. On dedicated servers, copy the HTML file to your local machine.

## CI Integration

<Tip>
  Export JSON results after each test run in your CI pipeline. Compare results across builds to detect regressions. The `timestamp` field lets you track when each run occurred.
</Tip>

You can automate export by combining commands:

```
/hrtk run
/hrtk export
```

The export file includes all suite results from the last run, making it a complete snapshot of test health.

<Note>
  HRTK does not automatically clean up old export files. If you run exports frequently, consider adding a cleanup step to your CI pipeline or server maintenance scripts.
</Note>

## Next Steps

* [Console Output](/running/console-output) - human-readable output format
* [Commands](/running/commands) - full command reference
* [Architecture](/server/architecture) - how results are collected internally