Debug, troubleshoot and record Cypress CI tests in Cloud

Integrate Cypress with alternative cloud services like Currents or Sorry Cypress.

Currents - a drop-in replacement for Cypress Dashboard. Run, debug, troubleshoot and analyze parallel CI tests in cloud. This is an enhanced version of Sorry Cypress with better security, performance, analytics, integrations and support.

Sorry Cypress - is an open-source, free alternative to Cypress Dashboard that unlocks unlimited parallelization, test recordings, and integration with GitHub, Slack and more.

Changelog | Compatibility | Documentation | License

Requirements

The package requires cypress version 10+ and NodeJS 14.7.0+

Setup

Install the package:

npm install cypress-cloud

Create a new configuration file: currents.config.js in the project’s root, set the projectId and the record key obtained from Currents or your self-hosted instance of Sorry Cypress:

// currents.config.js
module.exports = {
  projectId: "Ij0RfK",
  recordKey: "xxx",
  // Sorry Cypress users - set the director service URL
  cloudServiceUrl: "http://cy.currents.dev",
};

Add cypress-cloud/plugin to cypress.config.{js|ts|mjs}

// cypress.config.js
const { defineConfig } = require("cypress");
const { cloudPlugin } = require("cypress-cloud/plugin");
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      return cloudPlugin(on, config);
    },
  },
});

Usage

npx cypress-cloud --parallel --record --key <your_key> --ci-build-id hello-cypress-cloud

See all the available options npx cypress-cloud --help. Learn more about CI Build ID.

Example

See an example in examples/webapp directory.

Configuration

// currents.config.js
module.exports = {
  projectId: "Ij0RfK", // ProjectID obtained from https://app.currents.dev or Sorry Cypress
  recordKey: "XXXXXXX", // Record key obtained from https://app.currents.dev, any value for Sorry Cypress
  cloudServiceUrl: "https://cy.currents.dev", // Sorry Cypress users - the director service URL
  e2e: {
    batchSize: 3, // orchestration batch size for e2e tests (Currents only, read below)
  },
  component: {
    batchSize: 5, // orchestration batch size for component tests (Currents only, read below)
  },
};

Override the default configuration values via environment variables:

CURRENTS_API_URL - sorry-cypress users - set the URL of your director service
CURRENTS_PROJECT_ID - set the projectId
CURRENTS_RECORD_KEY - cloud service record key

Batched Orchestration

This package uses its own orchestration and reporting protocol that is independent of cypress native implementation. The new orchestration protocol allows multiple spec files to be batched together for better efficiency. You can adjust the batching configuration in cypress.config.js and use different values for e2e and component tests.

API

`run`

Run Cypress tests programmatically

run(params: CurrentsRunParameters): Promise<CypressCommandLine.CypressRunResult | CypressCommandLine.CypressFailedRunResult>

params - CurrentsRunParameters list of params compatible with Cypress Module API
returns results as a CypressRunResult

Example:

import { run } from "cypress-cloud";

const results = await run({
  reporter: "junit",
  browser: "chrome",
  config: {
    baseUrl: "http://localhost:8080",
    video: true,
  },
});

Troubleshooting

Enable the debug mode and run the command:

DEBUG=currents:* npx cypress-cloud run ...

Capture all the logs in a plain text file and submit an issue.

Testing

npm run test

Please note, we use esbuild for building and swc for testing. In addition, jest has built-in module aliases, but eslint does not. Beware of importing aliases in non-testing code.

Releasing

Beta channel

cd packages/cypress-cloud
npm run release -- --preRelease=beta && npm run release:npm -- -t beta

Latest channel

cd packages/cypress-cloud
npm run release && npm run release:npm -- -t latest

Localhost

docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
npm adduser --registry http://localhost:4873
npm login --registry http://localhost:4873
npm publish --registry http://localhost:4873 --tag beta

pkatseas/cypress-cloud