# allure-js-commons

> Allure JS Commons

Latest version **3.12.2** (published 2026-09-16) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install allure-js-commons
pnpm add allure-js-commons
yarn add allure-js-commons
bun add allure-js-commons
```

## Health

**Score 58/100 (C)** — status: active.

Positive: has types package; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.12.2 |
| Published | 2026-09-16 |
| First published | 2015-06-05 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | separate (@types/allure-js-commons) |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 282 |
| Author | Qameta Software |
| Maintainers | qameta-bot, baev, eroshenkoam, just-boris |
| Keywords | allure, codeceptjs, cypress, jasmine, jest, junit, mocha, newman, playwright, postman, report, reporter, test, testing, testops, vitest |

## Links

- npm: https://www.npmjs.com/package/allure-js-commons
- Repository: https://github.com/allure-framework/allure-js
- Homepage: https://allurereport.org/
- npm.io page: https://npm.io/package/allure-js-commons

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 3.12.2 (latest) — 2026-09-16
- 3.12.1 — 2026-09-09
- 3.12.0 — 2026-09-03
- 3.11.1 — 2026-09-01
- 3.11.0 — 2026-08-25
- 3.10.2 — 2026-06-26
- 3.10.1 — 2026-06-23
- 3.10.0 — 2026-06-10
- 3.9.0 — 2026-05-20
- 3.8.0 — 2026-05-11
- 3.7.2 — 2026-05-04
- 3.7.1 — 2026-04-09
- 3.7.0 — 2026-04-07
- 3.6.0 — 2026-03-06
- 3.5.0 — 2026-02-25
- … 101 more at https://npm.io/package/allure-js-commons/versions

## README

# allure-js-commons

> Common utilities for Allure framework JavaScript integrations

[<img src="https://allurereport.org/public/img/allure-report.svg" height="85px" alt="Allure Report logo" align="right" />](https://allurereport.org "Allure Report")

- Learn more about Allure Report at https://allurereport.org
- 📚 [Documentation](https://allurereport.org/docs/) – discover official documentation for Allure Report
- ❓ [Questions and Support](https://github.com/orgs/allure-framework/discussions/categories/questions-support) – get help from the team and community
- 📢 [Official annoucements](https://github.com/orgs/allure-framework/discussions/categories/announcements) – be in touch with the latest updates
- 💬 [General Discussion ](https://github.com/orgs/allure-framework/discussions/categories/general-discussion) – engage in casual conversations, share insights and ideas with the community

---

`allure-js-commons` is the shared runtime API and reporter SDK used by the packages in this repository. It gives you both:

- a high-level facade for test code, such as `allure.step()`, `allure.attachment()`, `allure.owner()`, and `allure.epic()`
- low-level building blocks for custom integrations, such as `ReporterRuntime`, writers, runtime message transport, and result model factories

Use it when you want to:

- enrich tests with Allure metadata from JavaScript or TypeScript
- write your own test framework integration
- build a custom adapter that emits standard `allure-results`
- reuse the same reporting model across multiple runners or tools

## Installation

Install the package with your package manager of choice:

```bash
npm install -D allure-js-commons
```

If you are building a custom integration, install your framework alongside it and add Allure Report separately when you want to render results:

- follow the [Allure Report 2 installation guide](https://allurereport.org/docs/install/) to use the `allure` CLI
- or install Allure Report 3 with `npm install -D allure` to use `npx allure`

## View the report

If your integration writes `./allure-results`, you can render it with either report generator.

Use Allure Report 2:

```bash
allure generate ./allure-results -o ./allure-report
allure open ./allure-report
```

Or use Allure Report 3:

```bash
npx allure generate ./allure-results
npx allure open ./allure-report
```

## Supported versions and platforms

- works in Node.js environments on Linux, macOS, and Windows
- used by the official integrations in this repository, which are validated in CI on Node.js 20 and 22
- intended for frameworks and tooling that can produce or consume Allure runtime messages and result files

## Overview

### High-level facade

The package root exports the API used directly inside tests:

- labels and links: `epic`, `feature`, `story`, `owner`, `severity`, `issue`, `tms`, `tag`
- descriptions and identifiers: `description`, `descriptionHtml`, `displayName`, `historyId`, `testCaseId`
- execution details: `parameter`, `step`, `logStep`
- attachments: `attachment`, `attachmentPath`, `globalAttachment`, `globalAttachmentPath`

These helpers delegate to the active test runtime, which integrations register with `setGlobalTestRuntime()`.

### Reporter SDK

The `allure-js-commons/sdk` entry points expose the pieces used by official integrations:

- `sdk/runtime`: runtime message transport and global runtime registration
- `sdk/reporter`: `ReporterRuntime`, writers, result factories, categories, environment info, and helper utilities
- `sdk`: shared types, runtime message definitions, serialization helpers, and metadata parsing helpers

## Basic usage in tests

```ts
import * as allure from "allure-js-commons";

await allure.epic("Authentication");
await allure.feature("Password sign-in");
await allure.owner("qa-team");
await allure.parameter("browser", "chromium");

await allure.step("Submit valid credentials", async () => {
  await allure.attachment("request", JSON.stringify({ login: "jane" }), {
    contentType: "application/json",
  });
});
```

## Sync facade

When your test code runs synchronously, or when you want to integrate with synchronous helpers such as matcher libraries, you can use the sync facade:

```ts
import * as allure from "allure-js-commons/sync";

allure.epic("Authentication");
allure.parameter("browser", "chromium");

allure.step("Submit valid credentials", () => {
  allure.attachment("request", JSON.stringify({ login: "jane" }), {
    contentType: "application/json",
  });
});
```

`allure-js-commons/sync` requires framework adapters to register sync runtime support. Until an adapter adds that support, the sync facade warns and safely no-ops.

`allure.step()` from the sync facade is strict-sync only. Its callback must complete synchronously and must not return a `Promise`.

## Creating your own integration

The official adapters in this repository follow the same basic flow:

1. Create a `ReporterRuntime` with a writer that persists `allure-results`.
2. Register a test runtime with `setGlobalTestRuntime()` so `allure-js-commons` calls inside tests can emit runtime messages.
3. Map your framework lifecycle events to `startTest`, `updateTest`, `stopTest`, `writeTest`, and optional scope or fixture methods.
4. Forward runtime messages from the active test into `ReporterRuntime.applyRuntimeMessages()`.

Here is a minimal example:

```ts
import { Stage, Status } from "allure-js-commons";
import type { RuntimeMessage } from "allure-js-commons/sdk";
import { ReporterRuntime, createDefaultWriter } from "allure-js-commons/sdk/reporter";
import { MessageTestRuntime, setGlobalTestRuntime } from "allure-js-commons/sdk/runtime";

class MyFrameworkRuntime extends MessageTestRuntime {
  constructor(private readonly forward: (message: RuntimeMessage) => void) {
    super();
  }

  async sendMessage(message: RuntimeMessage) {
    this.forward(message);
  }
}

const reporterRuntime = new ReporterRuntime({
  writer: createDefaultWriter({ resultsDir: "./allure-results" }),
});

let currentTestUuid: string | undefined;

setGlobalTestRuntime(
  new MyFrameworkRuntime((message) => {
    if (currentTestUuid) {
      reporterRuntime.applyRuntimeMessages(currentTestUuid, [message]);
    } else {
      reporterRuntime.applyGlobalRuntimeMessages([message]);
    }
  }),
);

export const onTestStart = (name: string, fullName: string) => {
  currentTestUuid = reporterRuntime.startTest({
    name,
    fullName,
    stage: Stage.RUNNING,
  });
};

export const onTestPass = () => {
  if (!currentTestUuid) return;
  reporterRuntime.updateTest(currentTestUuid, (result) => {
    result.status = Status.PASSED;
    result.stage = Stage.FINISHED;
  });
  reporterRuntime.stopTest(currentTestUuid);
  reporterRuntime.writeTest(currentTestUuid);
  currentTestUuid = undefined;
};

export const onTestFail = (error: Error) => {
  if (!currentTestUuid) return;
  reporterRuntime.updateTest(currentTestUuid, (result) => {
    result.status = Status.BROKEN;
    result.stage = Stage.FINISHED;
    result.statusDetails = {
      message: error.message,
      trace: error.stack,
    };
  });
  reporterRuntime.stopTest(currentTestUuid);
  reporterRuntime.writeTest(currentTestUuid);
  currentTestUuid = undefined;
};
```

This approach lets framework callbacks manage test lifecycle state while user code keeps using the regular `allure-js-commons` facade.

## Useful building blocks

- `ReporterRuntime`: creates and writes tests, fixtures, steps, attachments, categories, and environment info
- `createDefaultWriter()`: writes to `./allure-results` in normal runs and switches to a message writer in test mode
- `FileSystemWriter`, `InMemoryWriter`, `MessageWriter`, `MessageReader`: transport and persistence helpers
- `setGlobalTestRuntime()`: connects the facade API to the currently active framework runtime
- `MessageTestRuntime` and `MessageHolderTestRuntime`: ready-made runtime message implementations for adapters
- `createTestResult()`, `createStepResult()`, `createFixtureResult()`, `createTestResultContainer()`: factories for manual result construction

## Labels from environment variables

Allure allows you to apply labels to every test through environment variables. Use the `ALLURE_LABEL_<labelName>=<labelValue>` format.

#### Examples

```bash
ALLURE_LABEL_epic="Story 1" npm test
```

---
_Source: https://npm.io/package/allure-js-commons · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._