Skip to main content

Cypress Reporter

The Testream Cypress Reporter runs your Cypress tests and automatically uploads test results to Testream. You can use it as a CLI tool or integrate it directly into your Cypress configuration.

Installation​

npm install --save-dev @testream/cypress-reporter cypress-ctrf-json-reporter

Quick Start​

The easiest way to get started is using the CLI:

npx @testream/cypress-reporter -k $TESTREAM_API_KEY

This single command will:

  1. Run your Cypress tests
  2. Generate a CTRF report automatically
  3. Upload results to Testream (project key inferred from API key)

Option 2: Programmatic Configuration​

Add the reporter to your cypress.config.ts:

cypress.config.ts
import { defineConfig } from "cypress";
import { TestreamReporter } from "@testream/cypress-reporter";

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      new TestreamReporter({
        on,
        apiKey: process.env.TESTREAM_API_KEY,
        uploadEnabled: true,
      });
    },
  },
});

Then run your tests normally:

cypress run

CLI Options​

OptionTypeDefaultDescription
-k, --api-keystring-Required API key (unless --no-upload is used)
--project <path>stringcurrent dirPath to Cypress project
--results-path <path>string-Use existing CTRF file(s) instead of running tests
--branch <name>stringauto (CI)Git branch name
--commit-sha <sha>stringauto (CI)Git commit SHA
--repository-url <url>stringauto (CI)Git repository URL
--build-name <name>string-Build name
--build-number <num>stringauto (CI)Build number
--build-url <url>stringauto (CI)Build URL
--test-environment <env>string-Test environment (e.g., ci, staging)
--app-name <name>string-Application name
--app-version <ver>string-Application version
--test-type <type>string-Test type (e.g., e2e, integration)
--no-uploadbooleanfalseSkip uploading (validate + summarize only)
--fail-on-errorbooleanfalseExit with non-zero code if upload fails
-- <args>--Additional arguments passed to cypress run

Configuration Options​

When using programmatic configuration, these options are available:

OptionTypeDefaultDescription
onPluginEvents-Required Cypress plugin events object
apiKeystring-Required Testream API key
uploadEnabledbooleantrueEnable/disable automatic upload
failOnUploadErrorbooleanfalseFail test run if upload fails
outputDirstringctrfCTRF output directory
outputFilestringctrf-report.jsonCTRF report filename
screenshotbooleantrueInclude screenshots in report
minimalbooleanfalseGenerate minimal report
annotationsbooleanfalseInclude Cypress annotations
testTypestringe2eTest type (e.g., e2e, integration)
appNamestring-Application name
appVersionstring-Application version
branchNamestringautoGit branch name
commitShastringautoGit commit SHA
repositoryUrlstringautoGit repository URL
repositoryNamestringautoGit repository name
buildNamestring-Build name
buildNumberstringautoBuild number
buildUrlstringautoBuild URL
testEnvironmentstring-Test environment name

Examples​

Run tests and upload​

npx @testream/cypress-reporter -k $TESTREAM_API_KEY

Run tests from a specific project directory​

npx @testream/cypress-reporter -k $TESTREAM_API_KEY --project ./e2e

Pass additional arguments to Cypress​

npx @testream/cypress-reporter -k $TESTREAM_API_KEY -- --spec "cypress/e2e/**/*.cy.js"

Use existing CTRF results​

If you've already run your tests and have CTRF reports:

npx @testream/cypress-reporter -k $TESTREAM_API_KEY --results-path ctrf/ctrf-report.json

Add application and environment metadata​

npx @testream/cypress-reporter \
  -k $TESTREAM_API_KEY \
  --build-name "E2E Tests" \
  --test-environment ci \
  --app-name "My App" \
  --app-version 1.0.0 \
  --test-type e2e

Full Configuration Example​

cypress.config.ts
import { defineConfig } from "cypress";
import { TestreamReporter } from "@testream/cypress-reporter";

export default defineConfig({
  e2e: {
    baseUrl: "https://example.cypress.io",
    video: false,
    screenshotOnRunFailure: true,
    setupNodeEvents(on, config) {
      new TestreamReporter({
        on,
        // API Configuration
        apiKey: process.env.TESTREAM_API_KEY,

        // Upload Configuration
        uploadEnabled: true,
        failOnUploadError: false,

        // Output Configuration
        outputDir: "ctrf",
        outputFile: "ctrf-report.json",

        // Report Options
        screenshot: true,
        testType: "e2e",
        minimal: false,

        // Application Info
        appName: "My App",
        appVersion: "1.0.0",

        // Environment
        testEnvironment: process.env.TEST_ENV || "local",

        // Build Metadata
        buildName: "Cypress E2E Tests",
      });
    },
  },
});

GitHub Actions Example​

.github/workflows/cypress-tests.yml
name: Cypress Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Run Cypress tests and upload
        env:
          TESTREAM_API_KEY: ${{ secrets.TESTREAM_API_KEY }}
        run: |
          npx @testream/cypress-reporter \
            -k $TESTREAM_API_KEY \
            --test-environment ci \
            --app-name MyApp \
            --app-version 1.0.0 \
            --fail-on-error

Notes​

Peer Dependency​

The reporter requires cypress-ctrf-json-reporter as a peer dependency. Make sure it's installed:

npm install --save-dev cypress-ctrf-json-reporter

Screenshots and Artifacts​

Cypress screenshots captured during test runs are automatically included in the CTRF report when screenshot: true is set (default behavior).

Sample Project​

The testream/cypress-jira-reporter repository is a complete working example of a Cypress project integrated with Testream. It includes example tests, full reporter configuration, and a ready-to-use GitHub Actions workflow.

NPM Package​

What's Next?​