Skip to main content

Cypress Integration

Run your Cypress E2E tests as usual and have results automatically reported to ProvaLab.io. The plugin hooks into Cypress's after:run event to capture all test results at once.

Install​

npm install tms-node-sdk

Requirements: Node.js >= 18.0.0, Cypress >= 10.0.0

Configure​

1. Set environment variables​

export TMS_API_KEY=your-api-key
export TMS_API_URL=https://tms.yourcompany.com
export TMS_ORGANIZATION_ID=1
export TMS_PROJECT_ID=12

2. Add the ProvaLab.io plugin to your Cypress config​

cypress.config.ts
import { defineConfig } from 'cypress';
import { tmsCypressPlugin } from 'tms-node-sdk/cypress/reporter';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      tmsCypressPlugin(on, config);
    },
  },
});

JavaScript version:

cypress.config.js
const { defineConfig } = require('cypress');
const { tmsCypressPlugin } = require('tms-node-sdk/cypress/reporter');

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      tmsCypressPlugin(on, config);
    },
  },
});

Manual setup (if you need more control):

cypress.config.ts
import { defineConfig } from 'cypress';
import { TMSCypressReporter } from 'tms-node-sdk/cypress/reporter';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('after:run', async (results) => {
        const reporter = new TMSCypressReporter();
        await reporter.reportResults(results);
      });
    },
  },
});

Run​

npx cypress run
Cypress must run in headless mode

ProvaLab.io reporting only works with cypress run (headless mode). It does not work with cypress open (interactive mode) because the after:run event is not fired in interactive mode.

You'll see ProvaLab.io output after Cypress finishes:

========================================
  ProvaLab.io Cypress Integration
========================================
  Test Run ID: 849
  Project ID: 12
  Organization ID: 1
========================================

    [PASS] Login > should display login form (1.45s)
    [PASS] Login > should login successfully (2.31s)
    [FAIL] Checkout > should complete purchase (4.12s)

========================================
  ProvaLab.io Test Run Summary
========================================
  Test Run ID: 849
  Total:   3
  Passed:  2
  Failed:  1
  Skipped: 0
  Status:  FAILED
========================================

View Results in ProvaLab.io​

  1. Open ProvaLab.io and go to your project
  2. Click Test Runs in the sidebar
  3. Find the run named "Cypress: 2026-02-20 14:30:00" (or your custom name)
  4. Click into it to see individual test results with error messages

Option 1: Include the ID in the test title​

cypress/e2e/login.cy.js
describe('Login', () => {
  it('[TMS-301] should display login form', () => {
    cy.visit('/login');
    cy.get('form').should('be.visible');
    cy.get('input[name="email"]').should('exist');
  });

  it('[TMS-302] should login with valid credentials', () => {
    cy.visit('/login');
    cy.get('input[name="email"]').type('[email protected]');
    cy.get('input[name="password"]').type('password123');
    cy.get('button[type="submit"]').click();
    cy.url().should('include', '/dashboard');
  });
});

Option 2: Use a mapping file​

test-case-mapping.json
{
  "Login > should display login form": { "id": 301, "priority": "high" },
  "Login > should login with valid credentials": { "id": 302, "priority": "critical" }
}
export TMS_MAPPING_FILE=test-case-mapping.json
Mapping nested describes

Cypress maps test names as Describe > Nested Describe > test name, using > as the separator. Use this full path in your mapping file.

Advanced Configuration​

Custom test run name​

export TMS_TEST_RUN_NAME="E2E Smoke Tests - Chrome"

Environment tagging​

export TMS_ENVIRONMENT=staging

Run with specific browser​

npx cypress run --browser chrome
npx cypress run --browser firefox

ProvaLab.io captures the browser information from the spec file metadata.

Disable ProvaLab.io for local development​

export TMS_DISABLED=true
npx cypress run

Combine with other Cypress plugins​

The ProvaLab.io plugin hooks into after:run only, so it works alongside other plugins:

cypress.config.ts
import { defineConfig } from 'cypress';
import { tmsCypressPlugin } from 'tms-node-sdk/cypress/reporter';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // Other plugins
      require('@cypress/code-coverage/task')(on, config);

      // ProvaLab.io plugin (must be called, does not conflict)
      tmsCypressPlugin(on, config);

      return config;
    },
  },
});

Verify It Works​

  1. Set your environment variables
  2. Create a simple test:
cypress/e2e/tms-verify.cy.js
describe('TMS Integration', () => {
  it('[TMS-1] verify TMS integration', () => {
    cy.visit('https://example.com');
    cy.title().should('contain', 'Example');
  });
});
  1. Run it:
npx cypress run --spec cypress/e2e/tms-verify.cy.js
  1. Check the console output for the ProvaLab.io banner with a Test Run ID
  2. Open ProvaLab.io and confirm the test run appears under your project
Common issues
  • No ProvaLab.io output: Make sure you're using cypress run, not cypress open
  • "Not configured" message: Make sure TMS_API_KEY, TMS_ORGANIZATION_ID, and TMS_PROJECT_ID are all set
  • Plugin not loading: Check that the import path is tms-node-sdk/cypress/reporter (not just tms-node-sdk)