Getting started with Allure TestCafe

Generate beautiful HTML reports using Allure Report and your TestCafe tests.

Setting up

1. Prepare your project

1. Make sure Node.js is installed.

   The integration is tested against Node.js 18 and higher. Older versions may work, but we can't guarantee that.

2. Open a terminal and go to the project directory. For example:

   cd /home/user/myproject

3. Make sure Allure Report is installed. If it's not, follow the installation instructions. Note that Allure Report requires Java.

   Alternatively, install Allure Report 3 as a local npm package:

   npm install --save-dev allure

4. Install the Allure TestCafe reporter and make sure that TestCafe itself is also listed in the project's dependencies.

   npm

   npm install --save-dev testcafe testcafe-reporter-allure-official

   yarn

   yarn add --dev testcafe testcafe-reporter-allure-official

   pnpm

   pnpm add -D testcafe testcafe-reporter-allure-official

2. Configure the reporter

The recommended way to configure the reporter is with a JavaScript config file. This also enables test plan filtering, which is required for Allure's smart retry and agent-mode workflows.

Create a .testcaferc.cjs file at the root of your project:

const { createAllureTestPlanFilter } = require("testcafe-reporter-allure-official/testplan");

module.exports = {
  src: ["tests/**/*.test.js"],
  browsers: ["chromium:headless"],
  reporter: ["spec", "allure-official"],
  filter: createAllureTestPlanFilter(),
};

The createAllureTestPlanFilter() call returns undefined when ALLURE_TESTPLAN_PATH is not set, so TestCafe runs normally in that case. It is safe to leave enabled permanently.

INFO

JSON config files (.testcaferc.json) cannot use function-based filters. For the recommended Allure setup, use .testcaferc.js, .testcaferc.cjs, or the runner API.

If you only need the reporter without test plan support, you can use a JSON config:

{
  "src": ["tests/**/*.test.js"],
  "browsers": ["chromium:headless"],
  "reporter": ["spec", "allure-official"]
}

Or pass the reporter name on the command line:

testcafe "chromium:headless" tests -r spec,allure-official

Runner API

Use the TestCafe runner API when you need to set reporter options such as a custom output directory or link templates:

const createTestCafe = require("testcafe");
const createAllureTestCafeReporter = require("testcafe-reporter-allure-official");
const { createAllureTestPlanFilter } = require("testcafe-reporter-allure-official/testplan");

(async () => {
  const testcafe = await createTestCafe();

  try {
    const runner = testcafe.createRunner();

    await runner
      .src(["tests/**/*.test.js"])
      .browsers(["chromium:headless"])
      .filter(createAllureTestPlanFilter())
      .reporter(
        createAllureTestCafeReporter({
          resultsDir: "./out/allure-results",
        }),
      )
      .run();
  } finally {
    await testcafe.close();
  }
})();

See Configuration for all available reporter options.

3. Run tests

Run your TestCafe tests the same way as you would run them usually. For example:

npm

npx testcafe --config-file .testcaferc.cjs

yarn

yarn testcafe --config-file .testcaferc.cjs

pnpm

pnpm exec testcafe --config-file .testcaferc.cjs

This will save necessary data into allure-results or another directory, according to the configuration. If the directory already exists, the new files will be added to the existing ones, so that a future report will be based on them all.

4. Generate a report

Finally, convert the test results into an HTML report. This can be done by one of two commands:

• allure generate processes the test results and saves an HTML report into the allure-report directory. To view the report, use the allure open command.

• allure serve creates the same report as allure generate, then automatically opens the main page of the report in a web browser.

Writing tests

This section covers what the integration adds beyond standard TestCafe reporting:

• Metadata Annotation: Enhance test reports with descriptions, links, and other metadata.
• Test Organization: Structure your tests into clear hierarchies for better readability and organization, see organize tests.
• Step Division: Break down tests into smaller test steps for easier understanding and maintenance.
• Hooks: Use the runtime API inside fixture and test hooks to add labels, steps, and attachments from setup and teardown code.
• Parametrized Tests: Clearly describe the parameters for parametrized tests to specify different scenarios.
• Set labels globally: Use environment variables to set metadata and other labels.
• Attachments: Add screenshots and other files to the test report.
• Test Selection: Use a test plan file to select which tests to run, allowing for flexible test execution.
• Environment Details: Include comprehensive environment information to accompany the test report.

Allure TestCafe provides three ways to assign metadata and annotations to tests:

• Runtime API: call Allure's functions from allure-js-commons during test execution to add data dynamically.

  It is recommended to call these functions as close to the beginning of the test as possible so the data is recorded even if the test fails early.

• Meta API: set TestCafe fixture or test metadata using Allure-specific keys. This is the most robust approach: metadata is resolved before the test starts and is guaranteed to be present in the report.

• Title annotations: embed annotations directly in the test name using @allure.<type>=<value> syntax. These are extracted at test start time, before the test body runs.

Add metadata

Add descriptions, links, labels, and more to your test results. See the reference for the complete list.

Runtime API

const { displayName, owner, tags, severity } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`;

test("sign in", async () => {
  await displayName("Sign in");
  await owner("alice");
  await tags("Web interface", "Authentication");
  await severity("critical");
  // ...
});

Meta API

fixture`Authentication`.page`https://example.com/login`.meta({
  "allure.label.tag": ["Web interface", "Authentication"],
});

test.meta({
  "allure.label.owner": "alice",
  "allure.label.severity": "critical",
})("sign in", async (t) => {
  // ...
});

Title annotations

fixture`Authentication`.page`https://example.com/login`;

test(
  "sign in" +
    " @allure.label.owner=alice" +
    " @allure.label.tag=WebInterface" +
    " @allure.label.tag=Authentication" +
    " @allure.label.severity=critical",
  async () => {
    // ...
  },
);

Organize tests

As described in Improving navigation in your test report, Allure supports multiple ways to organize tests into hierarchical structures.

To specify a test's location in the behavior-based hierarchy:

Runtime API

const { epic, feature, story } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`;

test("sign in", async () => {
  await epic("Web interface");
  await feature("Essential features");
  await story("Authentication");
  // ...
});

Meta API

fixture`Authentication`.page`https://example.com/login`.meta({
  "allure.label.epic": "Web interface",
  "allure.label.feature": "Essential features",
});

test.meta({
  "allure.label.story": "Authentication",
})("sign in", async (t) => {
  // ...
});

Title annotations

fixture`Authentication`.page`https://example.com/login`;

test(
  "sign in" +
    " @allure.label.epic=WebInterface" +
    " @allure.label.feature=EssentialFeatures" +
    " @allure.label.story=Authentication",
  async () => {
    // ...
  },
);

To specify a test's location in the suite-based hierarchy:

Runtime API

const { parentSuite, suite, subSuite } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`;

test("sign in", async () => {
  await parentSuite("Tests for web interface");
  await suite("Tests for essential features");
  await subSuite("Tests for authentication");
  // ...
});

Meta API

fixture`Authentication`.page`https://example.com/login`.meta({
  "allure.label.parentSuite": "Tests for web interface",
  "allure.label.suite": "Tests for essential features",
});

test.meta({
  "allure.label.subSuite": "Tests for authentication",
})("sign in", async (t) => {
  // ...
});

Title annotations

fixture`Authentication`.page`https://example.com/login`;

test(
  "sign in" +
    " @allure.label.parentSuite=TestsForWebInterface" +
    " @allure.label.suite=TestsForEssentialFeatures" +
    " @allure.label.subSuite=TestsForAuthentication",
  async () => {
    // ...
  },
);

Divide a test into steps

To create steps and sub-steps, use the step() function from allure-js-commons. See the reference for the full API.

In addition, the reporter automatically captures TestCafe actions such as t.click(), t.typeText(), and t.expect() as steps. These automatic steps appear nested under any enclosing explicit step. To disable automatic action capture, set captureActionsAsSteps: false in the reporter config.

const { step, logStep, Status } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`;

test("sign in", async (t) => {
  await step("Fill credentials", async () => {
    await step("Enter login", async (ctx) => {
      await ctx.parameter("login", "demo-user");
      await t.typeText("#login", "demo-user");
    });
    await t.typeText("#password", "secret").click("#submit");
  });
  await logStep("Verified", Status.PASSED);
});

Hooks

The runtime API works in TestCafe fixture and test hooks. Labels, steps, and attachments added inside hooks are recorded as part of the owning test result.

Fixture hooks

const { owner, step, attachment } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`
  .beforeEach(async (t) => {
    await owner("alice");
    await step("Dismiss cookie banner", async () => {
      await t.click("#accept-cookies");
    });
  })
  .afterEach(async () => {
    await step("Capture session log", async () => {
      await attachment("session.log", "...", "text/plain");
    });
  });

test("sign in", async (t) => {
  // ...
});

Test hooks

const { severity, tag, step } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`;

test
  .before(async (t) => {
    await tag("smoke");
    await step("Seed credentials", async () => {
      await t.typeText("#username", "demo");
    });
  })
  .after(async () => {
    await severity("critical");
  })("sign in", async (t) => {
  // ...
});

Describe parametrized tests

A typical way to implement parametrized tests in TestCafe is to define a test in a loop. To display a parameter value in the test report, pass it to the parameter() function.

Additionally, any meta key that is not an Allure-specific key (allure.*) and whose value is a scalar string, number, boolean, or bigint is automatically added as a test parameter. This lets you annotate test variants with plain meta without any runtime API calls:

Runtime API

const { parameter } = require("allure-js-commons");

fixture`Authentication`.page`https://example.com/login`;

for (const login of ["johndoe", "[email protected]"]) {
  test(`sign in as ${login}`, async () => {
    await parameter("login", login);
    await parameter("timestamp", new Date().toISOString(), { excluded: true });
    // ...
  });
}

Meta API

fixture`Authentication`.page`https://example.com/login`;

for (const [login, role] of [
  ["johndoe", "user"],
  ["admin", "admin"],
]) {
  test.meta({ login, role })(`sign in as ${login}`, async (t) => {
    // login and role appear as parameters in the report
    // ...
  });
}

Set labels globally

Any labels, including custom ones, can be set via environment variables in your operating system. Here is an example (assuming you use the npm package manager):

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
npx testcafe --config-file .testcaferc.cjs

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
npx testcafe --config-file .testcaferc.cjs

Alternatively, set globalLabels in the reporter config (runner API only) to apply labels to every test result in the run. See Configuration.

Attach files

Reports generated by Allure can include any files attached to the test using allure.attachment() or allure.attachmentPath(). See Attachments.

const { attachment, attachmentPath } = require("allure-js-commons");
const { ContentType } = require("allure-js-commons");
const path = require("node:path");

fixture`Authentication`.page`https://example.com/login`;

test("sign in", async () => {
  // ...

  await attachment("Server response", JSON.stringify({ status: "ok" }), "application/json");

  await attachmentPath("Config file", path.join(__dirname, "config.txt"), ContentType.TEXT);
});

Automatic screenshots and videos

When TestCafe is configured to capture screenshots or record videos, the reporter automatically attaches them to the corresponding test result. No additional configuration is needed beyond your TestCafe setup.

Screenshots taken on failure are attached to the failed action step when TestCafe provides enough information to link them. Explicitly requested screenshots via t.takeScreenshot() appear as attachments on the takeScreenshot step.

When running tests across multiple browsers, screenshots and videos are attributed to the appropriate per-browser result. A Browser parameter is also automatically added to each result, showing the browser name.

Quarantine mode

When TestCafe runs tests in quarantine mode, the reporter attaches a Quarantine JSON file summarizing the result of each attempt. If the test is marked unstable by TestCafe — meaning it passed after earlier failures in the same run — the reporter also adds an "unstable" tag to the result automatically.

Warnings and errors

If TestCafe produces warnings during a test, they are automatically attached as a Warnings text file on the affected result. When a test produces multiple errors, or when a single error lacks complete diagnostic information, a formatted Errors text attachment is added to the result.

Select tests via a test plan file

When the ALLURE_TESTPLAN_PATH environment variable is set and points to an existing file, the createAllureTestPlanFilter() helper filters tests to only those listed in the plan.

Create an Allure test plan file:

{
  "version": "1.0",
  "tests": [
    {
      "selector": "tests/auth.test.js#Authentication#sign in"
    },
    {
      "id": "42"
    }
  ]
}

The selector format is <file>#<fixture>#<test>, where <test> is the clean test name with any title annotations stripped. Tests can also be matched by their Allure ID, set via the "allure.id" meta key or @allure.id=<value> title annotation. Because filtering runs before the test body executes, the runtime allureId() function cannot be used to register a test for plan-based selection.

Set ALLURE_TESTPLAN_PATH, then run normally. The filter only takes effect when the variable is set:

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
npx testcafe --config-file .testcaferc.cjs

Windows

$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
npx testcafe --config-file .testcaferc.cjs

Test plan filtering requires a JS/CJS config file or runner API so that createAllureTestPlanFilter() can be wired up as the TestCafe filter function. It is not possible to use this feature with a JSON config file.

Environment information

To include environment details on the report's main page, pass key-value pairs in the environmentInfo option when using the runner API. See Configuration.