Cypress Integration

• Setting Up the Reporting Layer
• Mapping Cypress Tests to PractiTest Tests
• Recommended Naming Approach
• Reporting Passed and Failed Results
• Using Cypress With CI/CD
• Sending Attachments
• Recommended First Implementation
• Best Practices
• Related Resources

This documentation explains how to report Cypress automated test results into PractiTest using the Auto Create a Run API.

Use this approach when your Cypress tests run outside PractiTest, for example from a local machine, GitHub Actions, Jenkins, GitLab CI, Azure DevOps, Bamboo, or another CI/CD tool, and you want the results to appear in PractiTest as automated test runs.

With this integration, Cypress remains responsible for running the tests, while PractiTest stores the results, execution history, attachments, and reporting data.

How It Works

The recommended approach uses the Cypress after:spec Node event, which fires after each spec file finishes and provides the results for every test in that spec. Because it runs in the Node environment, it can make API requests, but it cannot use cy commands.

Cypress spec finishes:

1. after:spec event fires with the spec’s results
2. Reporting layer processes each test result
3. Result is converted into a PractiTest API request
4. PractiTest finds or creates the test and instance
5. PractiTest creates the automated run

This keeps the integration centralized. You do not add PractiTest API calls inside individual Cypress tests.

For a complete, working implementation, see the Cypress example project rather than building the reporting layer from scratch. It includes a ready-to-adapt after:spec handler, PractiTest API calls, and screenshot attachment handling.

Prerequisites

Before setting up the integration, make sure you have:

• A PractiTest project and its ID
• A PractiTest Test Set and its ID (where the Cypress test results will be reported)
• A PractiTest API token with permission to create runs.
  • And, if PractiTest should create missing tests or instances automatically, permission to create those too
• A Cypress project or test suite
• A decision on how to map Cypress tests to PractiTest tests, by test ID or by test name (see below)

Setting Up the Reporting Layer

Register the after:spec handler in cypress.config.js (or .ts), inside setupNodeEvents:

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('after:spec', (spec, results) => {
        // send results to PractiTest here
      });
    },
  },
});

Store your PractiTest project ID, Test Set system ID, and API token as environment variables or CI/CD secrets, never commit them to source control.

Mapping Cypress Tests to PractiTest Tests

There are two common ways to map Cypress tests to PractiTest tests.

Option 1: Match by PractiTest Test ID

Use this when your tests already exist in PractiTest and you want strict control over the mapping. Each Cypress test is connected to a specific PractiTest test ID, so PractiTest always knows exactly which test should receive the result.

Best when:

• Your tests are already exist in PractiTest
• You want to avoid creating new tests automatically
• You need full control over the mapping
• Test names may change over time

Option 2: Match by Cypress Test Name

Use this when you want PractiTest to find or create tests based on the Cypress test name. PractiTest looks for a test with that name and creates one automatically if none exists.

Best when:

• You are starting a new automation integration
• You want a faster setup
• Your Cypress test names are stable and descriptive
• You do not want to maintain a manual mapping file

For the full attribute reference for both options — including test-type, description, and other optional test-attributes, see the Auto Create a Run API documentation.

Recommended Naming Approach

If you use name-based mapping, use a stable, descriptive pattern:

Area / Feature / Scenario

Examples:

• Login / Valid User Login
• Login / Invalid Password
• Checkout / Apply Discount Code

Cypress tests are often organized with describe and it blocks. Build the PractiTest test name from the full title chain:

describe('Login', () => {
  it('Rejects invalid password', () => {
    // test logic
  })
})

becomes:

Login / Rejects invalid password

Using the full title chain avoids duplicate names and keeps tests easy to identify in PractiTest.

Reporting Passed and Failed Results

PractiTest uses the exit-code field to determine the run status: 0 reports the run as Passed, and any other value reports it as Failed.

{
  "data": {
    "type": "instances",
    "attributes": {
      "set-id": 12345,
      "exit-code": 0,
      "run-duration": "00:00:18",
      "automated-execution-output": "Cypress test passed"
    },
    "test-attributes": {
      "name": "Login / Valid User Login"
    }
  }
}

For a failed test, send a short failure summary in automated-execution-output. For example, an assertion message, a timeout notice, or the selector that wasn’t found. This field supports up to 255 characters; for full failure detail, use attachments or a link to an external report instead.

Using Cypress With CI/CD

The same reporting layer works unchanged when Cypress runs from a CI/CD pipeline. No pipeline-specific setup is required, since after:spec runs as part of the normal Cypress test process:

CI/CD pipeline starts:

1. Cypress tests run
2. after:spec sends each spec’s results to PractiTest
3. PractiTest shows the latest automated run results

You can also send CI/CD metadata to PractiTest, build number, branch name, commit ID, environment, browser, pipeline URL, as custom fields or as part of the execution output, depending on your reporting needs.

Sending Attachments

Cypress can generate screenshots and videos when tests fail. Attach these to the PractiTest run so testers and developers can review failure evidence without leaving PractiTest.

A good first implementation is to attach screenshots only for failed tests, this keeps the integration useful without unnecessary storage or noise. Files are sent Base64-encoded; the maximum attachment size is 50 MB.

Recommended First Implementation

For the first version, keep the integration simple:

1. Report one PractiTest run per Cypress test
2. Use the after:spec event to centralize the reporting logic
3. Use stable Cypress test names, unless you already have PractiTest test IDs
4. Use exit-code to report passed or failed results
5. Send run-duration
6. Add a short automated-execution-output
7. Attach screenshots only for failed tests
8. Add custom fields only when needed for filtering or reporting

After the basic flow is working, expand to include additional metadata, advanced mapping, step-level reporting, videos, or richer attachments.

Best Practices

• Use stable, descriptive Cypress test names if you use name-based mapping
• Use PractiTest test IDs if you need strict control over the mapping
• Keep PractiTest API logic inside after:spec, avoid adding it to individual tests
• Start with test-level reporting before adding step-level reporting
• Attach failure evidence selectively
• Store API tokens securely in environment variables or CI/CD secrets, never commit tokens or .env files to source control
• Use custom fields only when they support reporting, filtering, or traceability

Related Resources

• Auto Create a Run API
• PractiTest API v2 Documentation
• Cypress Node Events Documentation
• PractiTest Cypress Example Project