Setup and usage instruction for cypress-cloud


The package requires cypress version 10+ and NodeJS 14.7.0+


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: "",
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);


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.


See an example in examples/webapp directory.


// currents.config.js
module.exports = {
projectId: "Ij0RfK", // ProjectID obtained from or Sorry Cypress
recordKey: "XXXXXXX", // Record key obtained from, any value for Sorry Cypress
cloudServiceUrl: "", // 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



Run Cypress tests programmatically
run(params: CurrentsRunParameters): Promise<CypressCommandLine.CypressRunResult | CypressCommandLine.CypressFailedRunResult>
import { run } from "cypress-cloud";
const results = await run({
reporter: "junit",
browser: "chrome",
config: {
baseUrl: "http://localhost:8080",
video: true,

Batched Orchestration

This package uses its own orchestration and reporting protocol that is independent of cypress native implementation. This approach provides several benefits, including more control and the ability to implement new features that are not supported by the native cypress orchestration. The new approach, however, introduced some challenges. Using cypress runner in "offline" mode requires restarting it often, which slows down the testing process.
Please note: the batched orchestration is not yet available for sorry-cypress users (only for
To improve the performance, the new orchestration protocol allows multiple spec files to be batched together for greater efficiency. You configure the batching in cypress.config.js and use different values for different testing types:
// currents.config.js
module.exports = {
// ...
e2e: {
batchSize: 3, // orchestration batch size for e2e tests (Currents only)
component: {
batchSize: 5, // orchestration batch size for component tests (Currents only)
Based on our benchmarks, the performance is comparable to that of the native orchestration, however, it can vary depending on your specific configuration and setup. Adjusting the batching configuration can help to achieve optimal results for e2e or component tests.

Native Orchestration Diagram

Batched Orchestration Diagram