Jest Circus Allure Environment

!Lint-Build-Test-Publish

A Jest Circus environment for Allure reporting.

!Allure Report

---

- 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

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

2. Update jest.config.js

_See the testEnvironment docs for configuration details._

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

3. Run tests

`shell
yarn test
`

4. Open the Allure report

`shell
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.

`js
// 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

`js
// 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._

`js
// 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.

$3

Add descriptions that document the tested functionality.

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

...
})
`

$3

Tag a test with a custom label.

_Set multiple tags using a , deliminator._

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

...
})
`

$3

Set an owner for a test.

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

..
})
`

$3

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

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

...
})
`

$3

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:

`TS
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
*/

...
})
`

$3

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:

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

...
})
`

👩‍🎓 Advanced

$3

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.

`TS
/**
* 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;
``