Cypress reporter

@qualflare/cypress is the Qualflare reporter for Cypress 12 or later: its plugin and support file write each run's results, with retries, screenshots, command steps and videos, to ./qualflare-results, and qf <identifier> collect uploads the folder as one launch.

Before you begin

• The Qualflare CLI, qf: Install the CLI.
• A saved login: qf login <identifier> with a project access token whose creator still holds the project role that uploads need Editor+ · project (requires the Editor role or higher in the project) (Authenticate with qf login).
• The Identifier of the environment the results belong to (Environments).

Install

npm install --save-dev @qualflare/cypress

Configure

Add both files:

// cypress.config.ts
import { defineConfig } from 'cypress';
import { qualflareCypress } from '@qualflare/cypress/plugin';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      return qualflareCypress(on, config, {
        environment: 'staging',
      });
    },
  },
});

// cypress/support/e2e.ts
import '@qualflare/cypress';

Every reporter shares the other settings: see Reporter configuration.

Set environment to the environment's Identifier: a name such as Staging fails the upload with HTTP 400 (Environment).

Run and upload

npx cypress run
qf <identifier> collect ./qualflare-results

Screenshots upload by default; add --upload-artifacts video for videos.

Run in CI

- name: Upload results to Qualflare
  if: ${{ !cancelled() }}
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
    QF_BRANCH: ${{ github.head_ref || github.ref_name }}
    QF_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
  run: |
    npm install -g @qualflare/cli
    qf login ci --force
    qf ci collect ./qualflare-results

if: ${{ !cancelled() }} uploads the results when tests fail, and QF_BRANCH and QF_COMMIT record a pull request's own branch and commit (Pull request branches). For GitLab CI/CD, Jenkins and Azure Pipelines, see Run the upload when tests fail.

Sharding and retries

Cypress gives reporters no shard number. Set QUALFLARE_SHARD_INDEX from your CI matrix, for example QUALFLARE_SHARD_INDEX: ${{ matrix.shard }}; every process writes its own file to the shared folder. See Merge sharded CI jobs into one launch.

Each attempt's status, duration and error is uploaded; steps, labels, tags and attachments come from the final attempt.

What gets uploaded

• Status, with the history of each retried attempt.
• Screenshots, taken automatically when a test fails.
• Step-by-step command traces.
• Labels, links, tags and attachments.

A test sets its own metadata with the qualflare calls:

import { qualflare } from '@qualflare/cypress';

it('logs in with valid credentials', () => {
  qualflare.label('epic', 'Authentication');
  qualflare.tag('smoke');

  qualflare.step('fill in credentials', () => {
    cy.get('#email').type('user@example.com');
    cy.get('#password').type('correct-horse-battery-staple');
  });
});

qf doesn't read the branch, commit, language or milestone from the report: set them on the upload (Branch, commit, language and milestone).

Troubleshooting

• No video on a passing spec: videoOnFailureOnly is on.
• environment "Staging" does not exist in this project: use the environment's Identifier, or pass --environment on the upload (Environment).
• Screenshots can't be downloaded: qf is older than 0.1.24. Upgrade qf.

Related

• Guides: Reporters · Upload results with qf collect · Sharded runs and result directories · Upload screenshots, videos and traces
• Reference: Reporter configuration · Cypress format
• More: Cypress test reporting in Qualflare