cypress-allure-adapter

This is allure adapter for Cypress providing realtime results. It is useful when using Allure TestOps - so you can watch tests execution. 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.

Some settings were taken from @shelex/cypress-allure-plugin, thank you!

Features:

• automatically adds all cypress commands to report (this is configurable)
• automatically adds hooks (before all, before each, after each, after all) to tests
• if before all or before each hook fails cypress skips all tests in spec file. This plugin will create tests that were not run for allure report 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
• Wraps custom commands into parent step, so report is cleaner
• has interface to set status message for tests - cy.allure().testDetails({ message: "This test is skipped because needs to be reviewed" })
• writes test files after each test - so you can watch execution in Allure TestOps
• gherkin support

Example report is here - Allure Report example

Table of Contents

1. Installation
2. Environment variables
3. To see allure report
4. Allure Interface
5. Advanced
   • after:spec event
   • Before run
   • Start/End test events
6. Examples
7. Allure TestOps
8. Troubleshooting
9. See also:
   • adding screenshots
10. Credits
11. Change log
12. Support

Installation

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

1. Update support

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

   // e2e.ts

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

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

Add allureAdapterSetup(); in your support/index.ts file (or e2e.ts file)

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:

  import { allureAdapterSetup } from '@mmisty/cypress-allure-adapter';
  
  allureAdapterSetup();
  // register custom commands here

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

2. Update plugins (setupNodeEvents)

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

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

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      configureAllureAdapterPlugins(on, config);
      
      return config;
    },
    // ...
  }
});

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

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      configureAllureAdapterPlugins(on, config);
      
      return config;
    },
    // ...
  }
});

3. Update environment variables

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

See other environment variables

4. Types

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

That's it! :tada:

Environment variables

| Variable | Description | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | alluretype: booleandefault: false | Enables reporting | | allureResultstype: stringdefault: allure-results | Path to allure results folder (where json files will be written) | | allureResultsWatchPathtype: stringdefault: 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. | | allureLogCyCommandstype: booleandefault: true | log cypress commands, by default will log all | | allureSkipCommandstype: stringex.: 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 | | allureSkipStepstype: stringex.: 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 | | allureWrapCustomCommandstype: true/false/stringdefault: true ex: - allureWrapCustomCommands: 'true' - allureWrapCustomCommands:'qaId,login' - allureWrapCustomCommands:'!qaValue' | will wrap custom commands, so custom command will have child steps in reportWhen 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. | | allureCleanResultstype: booleandefault: false | Will remove allure results on cypress start (it will be done once, after plugins are loaded) | | allureAttachRequeststype: booleandefault: false | Attach request/response body and status as files to request stepSeveral requests:One request: | | allureCompactAttachmentstype: booleandefault: true | Stringify requests attachments with spaces or not | | allureAddVideoOnPasstype: booleandefault: false | When true - will attach video for all tests (including passed), otherwise will attach videos only for failed, broken, unknown | | tmsPrefix type: stringex: 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: | | issuePrefix type: stringex: http://jira.com or http://jira.com/PROJECT-1/*/browse | The same as tmsPrefix - for issue cy.allure().issue('PROJ-02') | | allureShowDuplicateWarntype: booleandefault: false | Show console warnings about test duplicates. | | allureShowTagsInTitletype: booleandefault: undefined | Whether to show tags in test title or not. When undefined will keep title as is | | allureAddNonSpecialTagstype: booleandefault: true | Whether to add non-special tags to tests |

tmsPrefix and issuePrefix

tmsPrefix and issuePrefix - you can specify prefix to tms using this. Also link can be specified with * - it will be replced with id.

   // cypress.config.ts 
   env: {
     tmsPrefix: 'http://jira.com' 
     issuePrefix: 'http://jira.com/PROJECT-1/*/browse' 
   }  

    // test.spec.ts
    cy.allure().tms('ABC-1'); // http://jira.com/ABC-1
    cy.allure().issue('ABC-2'); // http://jira.com/PROJECT-1/ABC-2/browse

To see report

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

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:

// 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:

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

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

And also if you need to do something with test before it ends:

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.

Examples

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

Allure TestOps

Suites tree

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

No allure results folder

• make sure you have enabled plugin by 'allure' env variable
• to be continued

No results in allure folder

• make sure you are not overriding confi in plugins (env variables, and events)
• to be continued

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.