Example Project

See a complete working example: bistro-e2e-cypress — Cypress E2E tests with QA Sphere integration.

QA Sphere CLI Tool: Cypress Integration

This guide shows you how to integrate Cypress test results with QA Sphere using the QAS CLI tool.

Installation

Prerequisites

• Node.js version 18.0.0 or higher (Node.js 20+ recommended for Cypress)
• Cypress test project

Installation Methods

1. Via NPX (Recommended) Simply run npx qas-cli. On first use, you'll need to agree to download the package. You can use npx qas-cli in all contexts instead of the qasphere command.

   Verify installation:

   npx qas-cli --version

2. Via NPM

   npm install -g qas-cli

   Verify installation:

   qasphere --version

Configuration

The QAS CLI requires two environment variables to function properly:

• QAS_TOKEN - QA Sphere API token
• QAS_URL - Base URL of your QA Sphere instance (e.g., https://qas.eu2.qasphere.com)

You can create your API key under the QA Sphere settings.

To do that:

1. Go to Settings by clicking the gear icon in the top right corner.
2. Click API Keys
3. Click Create API Key and generate one

These variables can be defined in several ways:

1. Environment Variables: Export them in your shell:

   export QAS_TOKEN=your_token_here
   export QAS_URL=your_qas_url

2. .env File: Place a .env file in the current working directory:

   # .env
   QAS_TOKEN=your_token
   QAS_URL=your_qas_url

3. Configuration File: Create a .qaspherecli file in your project directory or any parent directory:

   # .qaspherecli
   QAS_TOKEN=your_token
   QAS_URL=your_qas_url
   
   # Example with real values:
   # QAS_TOKEN=tst0000001.1CKCEtest_JYyckc3zYtest.dhhjYY3BYEoQH41e62itest
   # QAS_URL=https://qas.eu1.qasphere.com

Cypress Configuration

To generate JUnit XML reports from Cypress, you need to configure a JUnit reporter. The recommended approach uses cypress-multi-reporters to output both console and JUnit XML simultaneously.

Install Reporter Dependencies

npm install --save-dev cypress-multi-reporters mocha-junit-reporter

Configure the Reporter

Create a reporter-config.json in your project root:

{
  "reporterEnabled": "spec, mocha-junit-reporter",
  "mochaJunitReporterReporterOptions": {
    "mochaFile": "cypress/reports/junit/results-[hash].xml"
  }
}

Then reference it in your cypress.config.ts:

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'https://your-app-url.com',
    specPattern: 'cypress/e2e/**/*.cy.ts',

    // Screenshots and videos
    screenshotOnRunFailure: true,
    video: true,
    videosFolder: 'cypress/videos',
    screenshotsFolder: 'cypress/screenshots',

    // Reporter configuration
    reporter: 'cypress-multi-reporters',
    reporterOptions: {
      configFile: 'reporter-config.json',
    },
  },
});

Key Configuration Points

• JUnit Reporter: mocha-junit-reporter generates XML files that QA Sphere can process
• Output File Pattern: The [hash] placeholder in mochaFile generates unique file names for each spec file
• Screenshots: Configure screenshotOnRunFailure: true to capture screenshots for failed tests
• Videos: Set video: true to record test runs

Multiple Report Files

Cypress with mocha-junit-reporter generates separate JUnit XML files per spec file (e.g., results-abc123.xml, results-def456.xml). When uploading, list all files:

npx qas-cli junit-upload cypress/reports/junit/results-*.xml

Using the junit-upload Command

The junit-upload command uploads JUnit XML test results to QA Sphere. It will automatically create a new test run if no run URL is provided, or upload to an existing run if a run URL is specified.

Basic Syntax

# Create new test run automatically
npx qas-cli junit-upload <path-to-junit-xml>

# Upload to existing test run
npx qas-cli junit-upload -r <run-url> <path-to-junit-xml>

Options

Option	Description
-r, --run-url	Upload results to an existing test run URL
--project-code	Project code for creating a new test run (can also be auto-detected from markers)
--run-name	Name template for the new test run. Supports {YYYY}, {MM}, {DD}, {HH}, {mm}, {ss}, {env:VAR} placeholders
--create-tcases	Automatically create test cases in QA Sphere for results without valid markers
--attachments	Detect and upload attachments with test results (screenshots, videos)
--force	Ignore API errors, invalid test cases, or attachment issues
--ignore-unmatched	Suppress individual unmatched test messages, show summary only
--skip-report-stdout	Control when to skip stdout blocks (on-success or never, default: never)
--skip-report-stderr	Control when to skip stderr blocks (on-success or never, default: never)

Cypress-Specific Examples

1. Create a new test run and upload results:

   # Run Cypress tests
   npm test
   
   # Upload all JUnit XML files
   npx qas-cli junit-upload cypress/reports/junit/results-*.xml

2. Upload to an existing test run:

   npx qas-cli junit-upload -r https://qas.eu1.qasphere.com/project/BD/run/23 cypress/reports/junit/results-*.xml

3. Upload with attachments (screenshots, videos):

   npx qas-cli junit-upload --attachments cypress/reports/junit/results-*.xml

4. Create a new run with a custom name template:

   npx qas-cli junit-upload --project-code BD --run-name "Cypress {YYYY}-{MM}-{DD}" cypress/reports/junit/results-*.xml

5. Auto-create test cases for unmatched results:

   npx qas-cli junit-upload --create-tcases cypress/reports/junit/results-*.xml

NPM Script Integration

Add convenient scripts to your package.json:

{
  "scripts": {
    "test": "cypress run --browser chrome",
    "test:upload": "npm test && npx qas-cli junit-upload --attachments cypress/reports/junit/results-*.xml"
  }
}

Then run:

npm run test:upload

Why this approach?

• Always up to date: Using npx qas-cli ensures you always get the latest version. For CI/CD environments where stability is critical, you can pin a specific version (e.g., npx [email protected])
• Convenience: A simple npm run test:upload is easier to remember
• CI/CD friendly: The script can be easily integrated into GitHub Actions, GitLab CI, or other pipelines
• Team consistency: Everyone runs the same command with the same flags

Test Case Marker Requirements

To ensure successful mapping of test results to QA Sphere test cases, your Cypress tests should include a QA Sphere test case marker.

A marker uses the format PROJECT-SEQUENCE (e.g., BD-023), where:

• PROJECT is your QA Sphere project code.
• SEQUENCE is the unique sequence number of the test case within the project.

This marker allows the CLI tool to correctly associate an automated test result with its corresponding test case in QA Sphere. Markers are used for searching and are displayed prominently in the QA Sphere Web UI.

Cypress Test Examples with Markers

// cypress/e2e/cart.cy.ts
describe('Cart Tests', () => {
  it('BD-023: User should see product list on the Checkout page', () => {
    cy.visit('/');
    // Add items to cart
    cy.get('.menu-item').first().find('.add-to-cart').click();
    cy.get('.cart-count').should('contain', '1');
    // Navigate to checkout
    cy.get('.checkout-btn').click();
    cy.get('.checkout-items').should('be.visible');
  });

  it('BD-022: User should place order with valid data', () => {
    cy.visit('/checkout');
    cy.get('#name').type('John Doe');
    cy.get('#email').type('[email protected]');
    cy.get('#payment').select('Cash on Delivery');
    cy.get('.place-order').click();
    cy.get('.success-message').should('be.visible');
  });
});

The marker should be included at the start of your test name. Examples of valid test case names:

• BD-023: User should see product list on the Checkout page
• BD-022: User should place order with valid data

Troubleshooting

Common Issues

1. JUnit XML files not found

   Error: File not found: cypress/reports/junit/results-*.xml

   Solution:

   • Ensure the JUnit reporter is properly configured in reporter-config.json
   • Verify that cypress-multi-reporters and mocha-junit-reporter are installed
   • Check that the output directory matches your upload command

2. Test cases not matching

   • Ensure your test names include the marker format (e.g., BD-023: Test name)
   • Verify the marker matches an existing test case in QA Sphere
   • Check that the project code in the marker matches your QA Sphere project
   • Use --create-tcases to auto-create test cases for unmatched results

3. Screenshots not uploading

   • Verify --attachments flag is included
   • Check that screenshotOnRunFailure: true is set in your Cypress config
   • Ensure attachment paths are relative to the working directory

Getting Help

For help with any command, use the -h flag:

npx qas-cli junit-upload -h

Complete Example Workflow

Here's a complete example of running Cypress tests and uploading to QA Sphere:

# 1. Set up environment variables (or use .env/.qaspherecli file)
export QAS_TOKEN=your_token_here
export QAS_URL=https://qas.eu1.qasphere.com

# 2. Run Cypress tests
npx cypress run --browser chrome

# 3. Upload results to QA Sphere
npx qas-cli junit-upload --attachments cypress/reports/junit/results-*.xml

Or as a single command with an npm script:

npm run test:upload

By following these guidelines, you can effectively integrate your Cypress test results with QA Sphere, streamlining your test management process.