Jest Circus Allure Environment

A Jest Circus environment for Allure reporting.

• Jest Circus Allure Environment
  • ❗️ Requirements
  • :rocket: Quick start
  • :camera_flash: Allure reporting in your tests
  • 🔧 Typescript & Intellisense setup
  • :gear: Options
  • 📈 DocBlocks
    • 🔍 Descriptions
    • 🏷 Tag
    • 👥 Owner
    • :part_alternation_mark: Severity
    • 📇 Behaviors (epics, features, stories)
    • 🔗 Links (Jira and TMS)
  • 👩‍🎓 Advanced
    • 🎛 Global Allure API

❗️ Requirements

| Resource | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Jest | A delightful JavaScript testing framework. | | Allure 2 CLI | "A Java jar command line tool that turns Allure result files into beautiful Allure reports." |

:rocket: Quick start

1. Add this package

yarn add --dev jest-circus-allure-environment

2. Update jest.config.js

See the testEnvironment docs for configuration details.

{
  "testEnvironment": "jest-circus-allure-environment",
  "testRunner": "jest-circus/runner"
}

3. Run tests

yarn test

4. Open the Allure report

allure serve ./allure-results

:camera_flash: Allure reporting in your tests

To provide more information in your reports you can use Docblock pragmas within your tests. For types support you'll need some additional configuration.

// simple.test.js

test('2 + 3 is 5', () => {
  /** My test description.
   * @epic Implement addition functionality
   * @tag Accounting
   */

  expect(2 + 3).toBe(5)
})

🔧 Typescript & Intellisense setup

1. Support Typescript & intellisense by loading the module into your jest.setup.js file

// jest.setup.js

import 'jest-circus-allure-environment' // Typescript or ESM
require('jest-circus-allure-environment') // CommonJS

2. Make sure your jest.setup.js file is properly configured.

See the setupFilesAfterEnv docs for configuration details.

// jest.config.js

{
  "setupFilesAfterEnv": ["./jest.setup.js"]
}

:gear: Options

Options that can be passed into the environmentOptions property of your jest.config.js

| Parameter | Description | Default | | --------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | | resultsDir | Path where Allure result files will be written. | "allure-results" | | jiraUrl | URL to Jira instance. Any @issue docblock pragmas will link to this URL. | undefined | | tmsUrl | URL to TMS instance. Any @tms docblock pragmas will link to this URL. | undefined | | environmentInfo | Key value pairs that will appear under the environment section of the Allure report | {} | | categories | Array of custom categories you wish to see in the Allure report. See an example | [] | | testPath | Path to your test files. This path will be subtracted from the Allure report when organizing tests into suites. | Jest.config.rootDir |

📈 DocBlocks

You may set code comments inside your tests called DocBlocks, that can be parsed for specific allure report pragmas. These are the supported DocBlock pragmas you may add to a test.

🔍 Descriptions

Add descriptions that document the tested functionality.

test('does something important, when triggered by user', () => {
  /** This uses a 3rd party API that typically undergoes maintenance on Tuesdays.
   */

  ...
})

🏷 Tag

Tag a test with a custom label.

Set multiple tags using a , deliminator.

test('does something important, when triggered by user', () => {
  /**
   * @tag beta
   * @tag feature-flagged, api-v3
   */

  ...
})

👥 Owner

Set an owner for a test.

test('does something important, when triggered by user', () => {
  /**
   * @owner ios-team
   */

  ..
})

:part_alternation_mark: Severity

Mark tests with a severity rating to indicate the importance of the tested functionality in respect to the overall application.

| Level | Description | | ---------------- | ---------------------------------------------------------------------------- | | blocker | Tests that if failing, will halt further development. | | critical | Tests that must pass; or risk disrupting crucial application logic. | | normal (default) | Tests that are of average importance to the overall application. | | minor | Tests that if failing, should only effect a small subset of the application. | | trivial | Tests that validate unreleased, disabled, or deprecated features. |

Example of setting a test as "critical" severity

test('does something important, when triggered by user', () => {
  /**
   * @severity critical
   */

  ...
})

📇 Behaviors (epics, features, stories)

Mark tests with a behavior label to organize tests in a feature based hierarchy.

| Level | Description | | ------- | ------------------------------------------------------------------------ | | epic | Tests that if fail, will effect the expected functionality of an epic. | | feature | Tests that if fail, will effect the expected functionality of a feature. | | story | Tests that if fail, will effect the expected functionality of story. |

Example:

test('validation message appears, when email field is skipped', () => {
  /**
   * @epic Automate user sign up
   * @feature Registration page
   * @story Validate required registration fields before creating new user
   */

  ...
})

🔗 Links (Jira and TMS)

Add Jira and TMS links to a test.

| Level | Description | | ----- | --------------------------------------------------------------------------------------------------- | | issue | Adds a link to the test report that will open an existing issue in Jira. | | tms | Adds a link to the test report that will open an existing test case in your test management system. |

Example:

test('validation message appears, when email field is skipped', () => {
  /**
   * @issue DEBT-60
   * @tms CORE-122
   */

  ...
})

👩‍🎓 Advanced

🎛 Global Allure API

An instance of the allure runtime will be available on the Node global variable. You can utilize it's APIs to provide custom reporting functionality.

/**
 * Returns the Allure test instance for the currently running test.
 */
allure.currentTest(): AllureTest;

/**
 * Adds a description to the report of the current test. Supports markdown.
 */
allure.description(markdown: string): void;

/**
 * Starts and returns a new step instance on the current executable.
 */
allure.startStep(name: string): StepWrapper;

/**
 * Starts a new Allure step, sets the status, and adds any provided attachments (optional), then ends the step.
 */
allure.logStep(
  name: string,
  status: Status,
  attachments?: Array<{ name: string; content: string; type: ContentType }>
): void;

/**
 * Add a parameter to the report of the current executable.
 */
allure.parameter(name: string, value: string): void;

/**
 * Attach a file to the report of the current executable.
 */
allure.attachment(
  name: string,
  content: Buffer | string,
  type: ContentType
);

/**
 * Add a issue link to the report of the current test.
 */
allure.issue(id: string): void;

/**
 * Add a TMS link to the report of the current test.
 */
allure.tms(id: string): void;

/**
 * Add a severity label to the report of the current test.
 */
allure.severity(severity: Severity): void;

/**
 * Add a epic label to the report of the current test.
 */
allure.epic(epic: string): void;

/**
 * Add a feature label to the report of the current test.
 */
allure.feature(feature: string): void;

/**
 * Add a story label to the report of the current test.
 */
allure.story(story: string): void;

/**
 * Add a tag label to the report of the current test.
 */
allure.tag(name: string): void;

/**
 * Add a custom label to the report of the current test.
 */
allure.label(name: string, value: string): void;