---
title: Bun configuration
description: Configuration properties for Allure Bun | Change allure-results directory | Set up link templates and categories
---

# Allure Bun configuration

The [Allure Bun](/docs/bun/) integration behavior can be configured through `globalThis.allureBunConfig` or the `ALLURE_BUN_CONFIG` environment variable.

## Providing configuration

### Using a custom preload file

Use a custom preload file when you need configuration values that cannot be represented as JSON — for example, listener functions or link template functions. The custom preload file must import `allure-bun/setup` after setting the configuration:

```ts
// preload.ts
import { Status } from "allure-js-commons";
import type { ReporterConfig } from "allure-js-commons/sdk/reporter";
import * as os from "node:os";

globalThis.allureBunConfig = {
  resultsDir: "allure-results",
  links: {
    issue: {
      nameTemplate: "Issue #%s",
      urlTemplate: "https://issues.example.com/%s",
    },
    tms: {
      nameTemplate: "TMS #%s",
      urlTemplate: "https://tms.example.com/%s",
    },
    jira: {
      urlTemplate: "https://jira.example.com/browse/%s",
    },
  },
  categories: [
    {
      name: "foo",
      messageRegex: "bar",
      traceRegex: "baz",
      matchedStatuses: [Status.FAILED, Status.BROKEN],
    },
  ],
  environmentInfo: {
    os_platform: os.platform(),
    os_release: os.release(),
    os_version: os.version(),
    bun_version: Bun.version,
  },
  globalLabels: {
    layer: "api",
  },
} satisfies ReporterConfig;

await import("allure-bun/setup");
```

Point `bunfig.toml` at your preload file instead of directly at `allure-bun/setup`:

```toml
[test]
preload = ["./preload.ts"]
```

### Using the environment variable

For simple deployments where all options can be expressed as JSON, pass configuration through the `ALLURE_BUN_CONFIG` environment variable:

**MacOS/Linux:**
```bash
export ALLURE_BUN_CONFIG='{"resultsDir":"allure-results","environmentInfo":{"node_version":"20"}}'
bun test
```

**Windows:**
```powershell
$Env:ALLURE_BUN_CONFIG = '{"resultsDir":"allure-results","environmentInfo":{"node_version":"20"}}'
bun test
```

`globalThis.allureBunConfig` takes priority over `ALLURE_BUN_CONFIG` if both are set.

## resultsDir

Path to the directory where Allure Bun will save the test results, see [How it works](/docs/how-it-works/). If the directory does not exist, it will be created. Defaults to `allure-results`.

You can also set the output directory using the `ALLURE_RESULTS_DIR` environment variable. The `resultsDir` option takes priority over the environment variable if both are set.

## links

A mapping of templates that can be used to construct full URLs from short identifiers.

For each type of link (see [`allure.link()`](/docs/bun-reference/#link)), you can specify the following:

- `nameTemplate` — a template for generating the link name when it is not provided.
- `urlTemplate` — a template for generating the link address when it is not provided.

Both templates must contain `%s` at the position where the identifier should be placed.

For example, with the configuration above, `await allure.issue("123")` will produce a link with the name `Issue #123` and the address `https://issues.example.com/123`. Allure will display the link with the appropriate icon for the `issue` type.

## categories

Define custom categories that will be used to distinguish test results by their errors; see [Categories](/docs/categories/).

This setting is an array, each item being an object representing one custom category. The objects may have the following properties:

- `name` — a category name.
- `messageRegex` — a regular expression that the test result's message should match.
- `traceRegex` — a regular expression that the test result's trace should match.
- `matchedStatuses` — an array of statuses that the test result should be one of.
- `flaky` — whether the test result should be marked as [flaky](/docs/test-stability/#flaky-tests).

## environmentInfo

Key-value pairs that will be displayed on the report's main page, see [Environment information](/docs/v2/readability/#environment-information).

## globalLabels

Labels applied to every test result in the run. Useful for tagging all results with a layer, team, or environment identifier without repeating it in every test.

Can be provided as an array of `{ name, value }` label objects:

```ts
globalThis.allureBunConfig = {
  globalLabels: [
    { name: "layer", value: "api" },
    { name: "team", value: "backend" },
  ],
};
```

Or as a plain object mapping label names to values. A name can map to a single string or an array of strings:

```ts
globalThis.allureBunConfig = {
  globalLabels: {
    layer: "api",
    team: "backend",
  },
};
```