cypress-allure-adapter

> This is Allure plugin for Cypress providing realtime results (compatible with Allure TestOps)
>

!actions
!npm downloads
!latest version

!cypress version
!supported cypress
!supported cypress
!supported cypress
!supported cypress

You can watch tests execution when using the plugin with Allure TestOps. It adds tests, steps, suites and screenshots during tests execution.

In the same time you can generate Allure Report from these results, and it will have all necessary fields.

To achieve compatibility with Allure TestOps (watch mode) this plugin has different architecture(based on ws) in comparison with existing plugins
which allows not to depend on cypress when writing test results.

Features:
- automatically adds all cypress commands to report (this is configurable)
- automatically adds videos / screenshots
- automatically adds hooks (before all, before each, after each, after all) to tests
- writes test results after each test - so you can watch execution in Allure TestOps
- will create tests that were not run (because of before or beforEach hooks failures) with unknown status - so total number of tests would be the same from run to run
- has interface to add metadata like tags, links, owner, host and others.
- has interface to add additional steps
- has interface to set status message for tests - cy.allure().testDetails({ message: "This test is skipped because needs to be reviewed" })
- wraps custom commands into parent step, so report is cleaner
- gherkin support
- adding meta information via test or suite title (ex. @tms("ABC-123"))

Example report is here - Allure Report example

Table of Contents

1. Installation
1. Environment variables
2. To see allure report
3. Allure Interface
4. Adding meta information
4. Advanced
- after:spec event
- Before run
- Start/End test events
- Start/End request events
- Add environment info
5. Examples
5. Allure TestOps
5. Troubleshooting
6. See also:
- adding screenshots
6. Credits
6. Change log
6. Support

Installation

Install adapter by npm i -D @mmisty/cypress-allure-adapter

$3

Import @mmisty/cypress-allure-adapter/support into your support/index.ts file (or e2e.ts/ e2e.js file)

``typescript
// e2e.ts

// import cypress-allure-adapter first to have all custom
// commands collapsed in report as parent command
import '@mmisty/cypress-allure-adapter/support';
// import other custom commands here
`

If you want all custom commands to be wrapped in report import adapter before adding(importing) any custom commands

Alternative way

Add allureAdapterSetup(); in your support/index.ts file (or e2e.ts file)
`typescript
import { allureAdapterSetup } from '@mmisty/cypress-allure-adapter';

allureAdapterSetup();
`
If you want all custom commands to be correctly wrapped in report register adapter before adding custom commands:

`typescript
import { allureAdapterSetup } from '@mmisty/cypress-allure-adapter';

allureAdapterSetup();
// register custom commands here
`


Javascript configuration

`javascript
// e2e.js

// import cypress-allure-adapter first to have all custom
// commands being collapsed in report as parent command
import '@mmisty/cypress-allure-adapter/support';
// import other custom commands here
`


$3


Add configureAllureAdapterPlugins(on, config); into your plugins file:

`typescript
// cypress.config.ts
import { configureAllureAdapterPlugins } from '@mmisty/cypress-allure-adapter/plugins';

export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
configureAllureAdapterPlugins(on, config);

return config;
},
// ...
}
});
`


Javascript configuration

`javascript
// cypress.config.js
const { configureAllureAdapterPlugins } = require("@mmisty/cypress-allure-adapter/plugins");

export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
configureAllureAdapterPlugins(on, config);

return config;
},
// ...
}
});
`


$3


In cypress.config.ts or cypress.config.js or in your environment files set allure env var to true.

See other environment variables

$3

[Typescript]: No need to setup types - should be done automatically

That's it! :tada:

Environment variables

| Variable | Description |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| allure
_type: boolean_
_default: false_ | Enables reporting |
| allureResults
_type: string_
_default: allure-results_ | Path to allure results folder (where json files will be written) |
| allureResultsWatchPath
_type: string_
_default: allure-results_ | This is needed when using Allure TestOps:
path to folder where results will be moved after finishing.
This path is what you need to watch when using Allure TestOps, but default this is not specified. When you use this path test results will start to appear in Allure TestOps, video will appear only after spec is finished.
If do not use this with Allure TestOps some videos may not be uploaded - videos will be uploaded only for 1 test from spec file. |
| allureLogCyCommands
_type: boolean_
_default: true_ | log cypress commands, by default will log all
!cy_steps |
| allureSkipCommands
_type: string_

ex.: screenshot,wait | Cypress commands separated with comma. Will skip only cypress commands used by cy. (any child commands will persist)
Will not log specified commands as steps in allure report, by default logs all commands. You can also use asterisk in command name - it will be assumed as any chars
|
| allureSkipSteps
_type: string_

ex.: screenshot,wait
ex.: "after each" hook,"before each" hook,"before all" hook* | Any allure steps that were created separated with comma (ex. cy.allure().startStep('my-step') - my-step can be added into allureSkipSteps env var, if you put into allureSkipCommands this command will still persist).
Will not log specified steps at all including child steps, by default logs all steps.
To skip before each / before all / after each or after all hooks their names can be added here. You can also use asterisk in step name - it will be assumed as any chars
|
| allureWrapCustomCommands
_type: true/false/string_
_default: true_

ex:
- allureWrapCustomCommands: 'true'
- allureWrapCustomCommands:'qaId,login'
- allureWrapCustomCommands:'!qaValue' | will wrap custom commands, so custom command will have child steps in report
When value has string with commands split by comma will wrap only these commands.
To exclude commands specify them starting with ! - all commands specified in this variable should have either ! or not have it

For this to work you should register allure plugin in setup files before any new commands are added.

!wrap-cmd |
| allureCleanResults
_type: boolean_
_default: false_ | Will remove allure results on cypress start (it will be done once, after plugins are loaded) |
| allureAttachRequests
_type: boolean_
_default: false_ | Attach request/response body and status as files to request step

Several requests:
!requests
One request:
!request |
| allureAddBodiesToRequests
_type: string_
_default: undefined_ | Add request/response bodies to request object of request:started/ request:ended custom events, see more |
| allureCompactAttachments
type: boolean
_default: true_ | Stringify requests attachments with spaces or not |
| allureAddVideoOnPass
_type: boolean_
_default: false_ | When true - will attach video for all tests (including passed), otherwise will attach videos only for failed, broken, unknown |
| tmsPrefix
_type: string_

ex: http://jira.com or http://jira.com/PROJECT-1//browse | You can specify prefix to tms using this. It will be concatenated with value when using cypress interface like cy.allure().tms('PROJ-01').
Also link can be specified with - it will be replaced with id.

Difference between tms and issue - will have different icons:

!links |
| issuePrefix
_type: string_

ex: http://jira.com or http://jira.com/PROJECT-1/*/browse | The same as tmsPrefix - for issue cy.allure().issue('PROJ-02') |
| allureShowDuplicateWarn
_type: boolean_
_default: false_ | Show console warnings about test duplicates. |
| allureShowTagsInTitle
_type: boolean_
_default: undefined_ | Whether to show tags in test title or not. When undefined will keep title as is (how to add tags?) |
| allureAddNonSpecialTags
_type: boolean_
_default: true_ | Whether to add non-special tags to tests. (what are special tags?) |
| allureIgnoreUncaughtExceptions
_type: string_
_default: adds all_ | Whether to add uncaught exception details to steps, value - exception messages split by comma, can use asterisk to replace any symbol |




$3


tmsPrefix and issuePrefix - you can specify prefix to tms using this.
Also link can be specified with * - it will be replced with id.
`javascript
// cypress.config.ts
env: {
tmsPrefix: 'http://jira.com'
issuePrefix: 'http://jira.com/PROJECT-1/*/browse'
}
`
`javascript
// test.spec.ts
it('test', () => {
cy.allure().tms('ABC-1'); // http://jira.com/ABC-1
cy.allure().issue('ABC-2'); // http://jira.com/PROJECT-1/ABC-2/browse
// ...
})
`

or you can put them as special tags in test title
`javascript
it('test @tms("ABC-1") @issue("ABC-2")', () => {
// ...
})
`

$3

In order to see Allure Report you need to install the CLI.

For nodejs you can use allure-commandline:

npm i -D allure-commandline

After installed allure command will be available.
To see a report in browser, run in console

`
allure serve
`

If you want to generate html version, run in console

`
allure generate
`

Report example: Allure Report

Allure Interface


There is allure interface available to use from tests - cy.allure() and Cypress.Allure.

For details see interface

Adding meta information

To add meta information to your tests you can either use allure interface or special tags.

Special tags does the same as allure interface with difference that you specify them through test or suite title:

`javascript
it('should login @feature("auth") @issue("ABC-2")', ()=> {
// ...
})
`

Advanced

#### after:spec event
This plugin uses after:spec plugins event to write videos and to write test results for Allure TestOps.

If you also use it in your cypress project cypress-allure-adapter
after:spec would be rewritten.

To avoid that you can add await reporter.afterSpec({ results }); into your Cypress plugin action after:spec:

`javascript
// cypress.config.ts
import { configureAllureAdapterPlugins } from '@mmisty/cypress-allure-adapter/plugins';

export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
const reporter = configureAllureAdapterPlugins(on, config);

on('after:spec', async (spec, results) => {
// your code in after spec
await reporter.afterSpec({ results });
})

return config;
},
// ...
}
});

`
#### Before run

Some operations like writing environment information, execution info or categories definitions
should be done once for a run.

To do that you need to modify your setupNodeEvents function:
`javascript
// cypress.config.ts
import { configureAllureAdapterPlugins } from '@mmisty/cypress-allure-adapter/plugins';

export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
const reporter = configureAllureAdapterPlugins(on, config);

// after that you can use allure to make operations on cypress start,
// or on before run start
on('before:run', details => {
reporter?.writeEnvironmentInfo({
info: {
os: details.system.osName,
osVersion: details.system.osVersion,
},
});
});

return config;
},
// ...
}
});
`


#### Start/End test events
If you need to add labels, tags or other meta info for tests you can use the following
additional events for Cypress.Allure interface:
- test:started is fired after tests started but before all "before each" hooks
- test:ended is fired after all "after each" hooks

`javascript
Cypress.Allure.on('test:started', test => {
Cypress.Allure.label('tag', 'started');
});
`

And also if you need to do something with test before it ends:
`javascript
Cypress.Allure.on('test:ended', test => {
Cypress.Allure.label('tag', 'ended');
Cypress.Allure.step('before end step');
});

`
You can put this into your support/index.ts file.

#### Start/End request events

This plugin provides custom events for start and end request(xhr/fetch) events (request:started, request:ended)

Using these events you can create your own handlers for requests - saving request bodies, adding specific attachemnts and etc.

Exmpale below:

`javascript
// this can be added to e2e.ts / e2e.js / support file

Cypress.Allure.on('request:started', (req, log) => {
Cypress.Allure.startStep(started ${req.method} ${req.url});
Cypress.Allure.attachment('request', JSON.stringify(req, null, ' '), 'application/json');
Cypress.Allure.endStep();

});

Cypress.Allure.on('request:ended', (req, log) => {
Cypress.Allure.startStep(ended ${req.method} ${req.status} ${req.url});
Cypress.Allure.attachment('request', JSON.stringify(req, null, ' '), 'application/json');
if(req.responseBody){
Cypress.Allure.parameter("responseBody", req.responseBody);
}
Cypress.Allure.endStep();
});

`

By default requests made by app do not store request/response bodies unless you intercept them.

So to access request bodies within custom events you need to add environemt variable allureAddBodiesToRequests with requests like you are interceptin them by cy.intercept:

`javascript
// cypress.config.ts
env: {
// ...
allureAddBodiesToRequests: '*', // will add bodies to all requests
}
// ...
`

or

`javascript
// cypress.config.ts
env: {
// ...
allureAddBodiesToRequests: '/endpoint1,/endpoint2**', // will add bodies only to requests with endpoint1 and endpoint2
}
// ...
`


#### Add environment info
To add environment information into Allure Report Environment section you need to update cypress config - setup node events:

`javascript
// cypress.config.ts
import { configureAllureAdapterPlugins } from '@mmisty/cypress-allure-adapter/plugins';

export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
const reporter = configureAllureAdapterPlugins(on, config);

on('before:run', details => {
reporter?.writeEnvironmentInfo({
info: {
os: details.system.osName,
osVersion: details.system.osVersion,
// here you can add other valuable for your purpose env variables
},
});
});

return config;
},
// ...
}
});
`
Please note: if your project or other cypress plugins you've added use before:run event - it may be overridden unless you are using
cypress events forwarder.

Examples

- Here is Javascript example of using the plugin - cypress-allure-adapter-example
- Allure Report example

Allure TestOps

To have compatibility with Allure Testops set environment variables:
- allureResults
- allureResultsWatchPath - this is the directory where test files ready for TestOps will be moved. It is suggested to use allure-results/watch when the environment variable is either not set or is set to allure-results

When starting tests in watch mode with allurectl set allure-results path to like:
`
allurectl watch --results 'allure-results/watch' -- npm run
`

Note: not setting the may result in videos being attached to only one test from the spec file. Other issues may also occur.




$3


To have correct suites tree you need to set up Allure TestOps:
1. Go to Administration section (for the whole application) -> Custom Fields section
2. Create 3 new fields if they not exist already: Parent Suite, Suite, Sub Suite
3. Go to Settings section for the project -> Custom Fields
4. Add mapping to newly added fields:
- type key parentSuite and select from dropdown custom field Parent Suite
- type key suite and select from dropdown custom field Suite
- type key subSuite and select from dropdown custom field Sub Suite
5. Open Trees section from project settings
6. Add or modify Suites tree with the following chain: Parent Suite -> Suite -> Sub Suite

Troubleshooting

To see debug log run cypress with DEBUG env variable like: DEBUG=cypress-allure* npm run cy:open

$3

- make sure you have enabled plugin by allure` env variable
- to be continued

$3

- make sure you are not overriding config in plugins (env variables, and events)
- make sure you return config object within setupNodeEvents

Credits

Thanks to @shelex, without his plugin this plugin would have been harder to start.

Change log

see change log

Support

Mostly, I develop this plugin during
my free time. However, I need your
support to take it to the next level.
Your donation will directly contribute
to the further development of this
plugin, allowing me to dedicate more
time and resources to enhancing its
features, improving user experience,
and ensuring its compatibility with the
latest versions. Help this plugin to grow
by donating - paypal.