[](https://github.com/facebook/jest) [](https://github.com/xojs/xo) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%
npm install jest-allure-circusshell
yarn add --dev jest-circus-allure
`
2. Update jest.config.js
_See the testEnvironment docs for configuration details._
`JSON
{
"testEnvironment": "jest-circus-allure",
"testRunner": "jest-circus/runner"
}
`
OR use this at the top of your testEnv file
`js
const AllureEnvironment = require('jest-allure-circus').default
`
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
*/
...
})
`
$3
Test Case ID in Allure.
Example:
`TS
test('validation message appears, when email field is skipped', () => {
/**
* @allureId 92066
*/
...
})
`
👩🎓 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;
/**
* Add Test Case ID in Allure.
*/
allure.allureId(id: string, index?: number): void;
``