search

currents-dev / cypress-cloud

Debug, troubleshoot and record Cypress CI tests in Cloud
https://currents.dev
Other
47 stars 16 forks source link
ci cypress e2e parallel sorry-cypress

readme

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

Table of Contents

Requirements

Setup

Install the package:

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

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

// cypress.config.js
import { defineConfig } from "cypress";
import { cloudPlugin } from "cypress-cloud/plugin";

export default defineConfig({
  e2e: {
    video: true; // enable video for cypress@13+
    async setupNodeEvents(on, config) {
      const result = await cloudPlugin(on, config);
      return result;
    },
  },
});

Add cypress-cloud/support to Cypress Support file (matching your test type - e2e or component, or both)

import "cypress-cloud/support";

Usage

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

cypress-cloud is designed for use in a headless mode in a CI environment, it provides the same flags and options as cypress command, but certain flags are preset and hidden. See all the available options npx cypress-cloud --help.

Learn more about CI Build ID and Parallelization.

Example

See an example in examples/webapp directory.

Configuration

// currents.config.js
module.exports = {
  projectId: "Ij0RfK", // Project Id 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
  // Additional headers for network requests, undefined by default
  networkHeaders: {
    "User-Agent": "Custom",
    "x-ms-blob-type": "BlockBlob",
  },
  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)
  },
  retry: {
    hardFailureMaxRetries: 2, // max retries for hard Cypress failures, a hard failure is when Cyrpess crashes and doesn't report back any results (see https://docs.cypress.io/guides/guides/module-api#Handling-errors)
  },
};

Configuration File Discovery

cypress-cloud will search for a configuration file as follows:

The configuration file will be read using import() expression. Please make sure to use the correct syntax if you're using ESM modules (see the guide below).

Configuration Overrides

You can override the configuration values via environment variables:

The configuration variables will resolve as follows:

Batched Orchestration

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

API

run

Run Cypress tests programmatically. See ./examples/webapp/scripts for examples.

run(params: CurrentsRunAPI): Promise<CypressCommandLine.CypressRunResult | undefined>

Example:

import { run } from "cypress-cloud";

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

Guides

Usage with @cypress/grep

The package is compatible with @cypress/grep.

@cypress/grep modifies cypress configuration and alters specPattern property. Install @cypress/grep before cypress-cloud/plugin to apply the modified configuration. For example:

import { defineConfig } from "cypress";
import grepPlugin from "@cypress/grep/src/plugin";
import { cloudPlugin } from "cypress-cloud/plugin";

export default defineConfig({
  e2e: {
    // ...
    async setupNodeEvents(on, config) {
      grepPlugin(config);
      const result = await cloudPlugin(on, config);
      return result;
    },
  },
});

Please refer to the issue for details.

Setup with existing plugins

Preserving config.env values

The config parameter of setupNodeEvents(on, config) has pre-defined config.env values. Please make sure to preserve the original config.env value when altering the property. For example:

import { defineConfig } from "cypress";
import { cloudPlugin } from "cypress-cloud/plugin";

export default defineConfig({
  e2e: {
    // ...
    async setupNodeEvents(on, config) {
      const enhancedConfig = {
        env: {
          ...config.env, // 👈🏻 preserve the original env
          customVariable: "value",
        },
      };
      const result = await cloudPlugin(on, enhancedConfig);
      return result;
    },
  },
});

Chaining config

Certain plugins (e.g. @cypress/grep) modify or alter the config parameter and change the default Cypress behaviour. Make sure that cypress-cloud is initialized with the most recently updated config, e.g.:

import { defineConfig } from "cypress";
import { cloudPlugin } from "cypress-cloud/plugin";

export default defineConfig({
  e2e: {
    // ...
    async setupNodeEvents(on, config) {
      const configA = pluginA(on, config); // configA has the modified config from pluginA
      const configB = pluginB(on, configA); // configA has the modified config from pluginA + pluginB
      // ...
      const configX = pluginX(on, configY); // configX has the modified config from all preceding plugins
      const result = await cloudPlugin(on, configX); // cloudPlugin has the accumulated config from all plugins
      return result;
    },
  },
});

Event callbacks for multiple plugins

cypress-cloud/plugin uses certain Cypress Plugin events. Unfortunately if there are mutliple listeners for an event, only the last listener is called (see the GitHub issue). Setups with multiple plugins can create conflicts - one plugin can replace listeners of others.

The existing workaround is to patch the on function by using either of:

For example:

import { defineConfig } from "cypress";
import { cloudPlugin } from "cypress-cloud/plugin";
import patchCypressOn from "cypress-on-fix";

export default defineConfig({
  e2e: {
    // ...
    async setupNodeEvents(cypressOn, config) {
      const on = patchCypressOn(cypressOn);
      // the rest of the plugins use the patched "on" function
      const configAlt = somePlugin(on, config);
      const result = await cloudPlugin(on, configAlt);
      return result;
    },
  },
});

Spec files discovery

cypress-cloud discovers the spec files using globby patterns according to the following logic:

Enable the debug mode to troubleshoot files discovery: DEBUG=currents:specs npx cypress-cloud ...

Usage with ESM project

For ESM projects ("type": "module" in package.json) you can use one of the following formats:

Also, make sure that your cypress.config.js|mjs|cjs|ts is formatted accordingly. See examples in ./e2e directory.

Troubleshooting

Enable the debug mode by adding --cloud-debug true | all | cypress | currents | commit-info flag

# show all the debug information
npx cypress-cloud run ... --cloud-debug

# show only currents related debug information
npx cypress-cloud run ... --cloud-debug currents,commit-info

Capture all the logs as a plain text file and share it with the support team for further troubleshooting.

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

Publishing from packages/cypress-cloud:

docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
npm adduser --registry http://localhost:4873
npm login --registry http://localhost:4873
npm_config_registry=http://localhost:4873  npm run release:npm -- --tag latest

Using:

npm install cypress-cloud --registry http://localhost:4873

License

GNU General Public License Version 3

Copyright (C) 2023 Currents Software Inc https://currents.dev.

This is free software, and you are welcome to redistribute it under certain conditions. This program comes with no warranty. Parts of this program are MIT licensed. Refer to the license for details https://github.com/currents-dev/cypress-cloud/blob/main/LICENSE.md

Disclaimer

This software is not affiliated with Cypress.io Inc. All third-party trademarks and materials (including logos, icons and labels) referenced herein are the property of their respective owners. The third-party products or services that this software connects to are subject to their respective owners, please refer to their intellectual property and terms of service agreements.