Jest Circus Allure Environment
A Jest Circus environment for Allure reporting.
❗️ 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." |
🚀 Quick start
- Add this package
yarn add --dev jest-circus-allure-environment
- Update
jest.config.js
See the testEnvironment docs for configuration details.
{
"testEnvironment": "jest-circus-allure-environment",
"testRunner": "jest-circus/runner"
}
- Run tests
yarn test
- Open the Allure report
allure serve ./allure-results
📸 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
- 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
- Make sure your
jest.setup.js
file is properly configured.
See the setupFilesAfterEnv docs for configuration details.
// jest.config.js
{
"setupFilesAfterEnv": ["./jest.setup.js"]
}
⚙️ 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
*/
..
})
〽️ 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;