@qualflare/cypress

A native Cypress reporter for Qualflare — captures test results directly from your Cypress run: suite/test status, per-attempt retry history, screenshots, step-by-step command traces, and author-facing metadata (labels, links, tags, custom attachments) — and writes them into a report directory that qualflare-cli uploads. No post-hoc file parsing, no intermediate report format to hand-roll, no network access needed from inside your Cypress run.

Install

npm install --save-dev @qualflare/cypress

Requires Cypress >=12.0.0 (installed separately as a peer dependency). Node >=18 for Cypress 12–14; Cypress 15 itself requires Node >=20.

The peer range is deliberately open-ended rather than capped at a known-good major, so a new Cypress release never hard-blocks npm install for you. Every major from 12 through 15 is exercised in CI against a real cypress run; majors newer than that are untested but not refused — please open an issue if one misbehaves.

(Contributors: the repo itself now develops against Cypress 15, which requires Node >=20.1. The >=18 floor above is the consumer requirement and still holds for Cypress 12–14.)

Quickstart

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

Run your tests as usual — every cypress run writes a Collect report (JSON, plus any video attachments) into ./qualflare-results by default. No token or network access is needed for this step; the reporter itself never makes a network call:

npx cypress run

Then, in the same CI job, hand that directory to qualflare-cli — the step that actually uploads results, required after every run, sharded or not:

npm install -g @qualflare/cli
qf login my-project "$QUALFLARE_TOKEN" --force
qf my-project collect ./qualflare-results

Requires @qualflare/cli v0.1.24 or newer. Screenshots are written into outputDir and referenced by name (localImagePath) instead of being base64-inlined into the report, the same way videos already were. An older CLI does not read the field, and because such an attachment carries neither content nor a storage key the server records it from its name alone — an undownloadable placeholder. Upgrade the CLI before upgrading this reporter.

Videos are opt-in; screenshots are not. collect uploads the report and the screenshots always, but a video only when asked: --upload-artifacts=video (or QF_UPLOAD_ARTIFACTS=video). Named kinds are added to that default, so asking for video does not turn screenshots off; --upload-artifacts=none declines everything, screenshots included. Nothing is dropped silently — collect prints how many it skipped and the exact flag to include them.

That's it — suite/test results, retries, and automatic-on-failure screenshots show up as one Launch once qualflare-cli collect runs. examples/basic/ has a runnable project demonstrating the same flow end to end, including the qualflare.* metadata API.

Enriching your tests

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('[email protected]');
    cy.get('#password').type('correct-horse-battery-staple');
  });

  qualflare.step('submit and verify redirect', () => {
    cy.get('#submit').click();
    cy.url().should('include', '/dashboard');
  });
});

See docs/METADATA-API.md for the full reference (labels, links, tags, description, priority, parameters, custom attachments, nested steps).

Configuration

Every option can be set either as a plugin option (qualflareCypress(on, config, options)) or via a QUALFLARE_* environment variable. Full table, precedence rules, and auto-detection behavior (git branch/commit, CI provider/build/PR, browser/OS) in docs/CONFIGURATION.md.

One option is worth calling out because it fails late: environment is matched against the environment's uid (slug), not its display name, so Staging in the UI is staging here. A wrong value cannot fail at run time — this package makes no network calls — so the run succeeds and collect 404s afterwards. See the note in the configuration docs.

Test reports

This plugin is tested with itself. e2e/ is a Cypress suite covering this package's own behaviour — the metadata API, nested steps, image attachments and per-attempt retry history — run by this plugin and uploaded to Qualflare on every merge to main. The results below are that suite's, reported through the code this README documents:

Every case there is meant to pass, so a red run is a real regression rather than a fixture that fails on purpose. Deliberately-failing cases live in test/integration/, which is never uploaded.

Known limitations

• Retries carry per-attempt errors, but everything else is the final attempt — Case.attempts records each attempt's status, duration and error; steps, labels, links, tags, priority, properties and attachments come from the last attempt only, so an abandoned attempt's step trace is discarded rather than replayed alongside the final one.

Full details in docs/LIMITATIONS.md.

Development

npm run typecheck   # tsc --noEmit
npm run lint        # eslint .
npm run build       # tsup — dual ESM+CJS, .d.ts
npm test            # unit tests (vitest)
npm run test:integration   # spawns a real cypress run against a fixture project, asserts on its outputDir report

Release process: see RELEASING.md.

License

Apache-2.0