{"id":22400131,"url":"https://github.com/currents-dev/cypress-cloud-private","last_synced_at":"2025-03-27T00:17:30.949Z","repository":{"id":269062888,"uuid":"685690389","full_name":"currents-dev/cypress-cloud-private","owner":"currents-dev","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-25T06:56:02.000Z","size":4434,"stargazers_count":0,"open_issues_count":12,"forks_count":1,"subscribers_count":2,"default_branch":"fix/cypress-13","last_synced_at":"2025-03-25T04:52:20.917Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/currents-dev.png","metadata":{"files":{"readme":".github/README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-31T19:37:16.000Z","updated_at":"2024-12-18T17:45:32.000Z","dependencies_parsed_at":"2024-12-20T16:54:33.309Z","dependency_job_id":"b91d77ea-5192-4e76-a69f-84356af42f52","html_url":"https://github.com/currents-dev/cypress-cloud-private","commit_stats":null,"previous_names":["currents-dev/cypress-cloud-private"],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/currents-dev%2Fcypress-cloud-private","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/currents-dev%2Fcypress-cloud-private/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/currents-dev%2Fcypress-cloud-private/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/currents-dev%2Fcypress-cloud-private/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/currents-dev","download_url":"https://codeload.github.com/currents-dev/cypress-cloud-private/tar.gz/refs/heads/fix/cypress-13","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245755683,"owners_count":20667027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T08:11:29.852Z","updated_at":"2025-03-27T00:17:30.930Z","avatar_url":"https://github.com/currents-dev.png","language":"TypeScript","readme":"# Debug, troubleshoot and record Cypress CI tests in Cloud\n\nIntegrate Cypress with alternative cloud services like Currents or Sorry Cypress.\n\n**[Currents](https://currents.dev/?utm_source=cypress-cloud)** - 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.\n\n**[Sorry Cypress](https://sorry-cypress.dev/?utm_source=cypress-cloud)** - is an open-source, free alternative to Cypress Dashboard that unlocks unlimited parallelization, test recordings, and integration with GitHub, Slack and more.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"830\" src=\"https://user-images.githubusercontent.com/1637928/213367982-78987b7a-411a-4d2e-9486-ca204847022e.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"../CHANGELOG.md\"\u003eChangelog\u003c/a\u003e | \u003ca href=\"https://currents.dev/readme/guides/cypress-compatibility\"\u003eCompatibility\u003c/a\u003e |\n\u003ca href=\"https://currents.dev/readme\"\u003eDocumentation\u003c/a\u003e | \u003ca href=\"https://github.com/currents-dev/cypress-cloud/blob/main/LICENSE.md\"\u003eLicense\u003c/a\u003e\n\n\u003c/p\u003e\n\n## Requirements\n\n- Cypress version 10+\n- NodeJS 16+\n\n## Setup\n\nInstall the package:\n\n```sh\nnpm install cypress-cloud\n```\n\n- Create a new configuration file: `currents.config.js|mjs|cjs` in the Cypress project’s root. Use `--cloud-config-file` to explicitly provide the configuration file. Using ESM project? See the guide below.\n- Set the `projectId` and the record key obtained from [Currents](https://app.currents.dev) or your self-hosted instance of Sorry Cypress:\n\n```js\n// currents.config.js\nmodule.exports = {\n  projectId: \"Ij0RfK\",\n  recordKey: \"xxx\",\n  // Sorry Cypress users - set the director service URL\n  cloudServiceUrl: \"https://cy.currents.dev\",\n};\n```\n\nAdd `cypress-cloud/plugin` to `cypress.config.{js|ts|mjs}`\n\n```js\n// cypress.config.js\nconst { defineConfig } = require(\"cypress\");\nconst { cloudPlugin } = require(\"cypress-cloud/plugin\");\nmodule.exports = defineConfig({\n  e2e: {\n    setupNodeEvents(on, config) {\n      return cloudPlugin(on, config);\n    },\n  },\n});\n```\n\n## Usage\n\n```sh\nnpx cypress-cloud --parallel --record --key \u003cyour_key\u003e --ci-build-id hello-cypress-cloud\n```\n\n`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`.\n\nLearn more about [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id) and [Parallelization](https://currents.dev/readme/guides/parallelization).\n\n## Example\n\nSee an example in [examples/webapp](https://github.com/currents-dev/cypress-cloud/blob/main/examples/webapp) directory.\n\n## Configuration\n\n```js\n// currents.config.js\nmodule.exports = {\n  projectId: \"Ij0RfK\", // Project Id obtained from https://app.currents.dev or Sorry Cypress\n  recordKey: \"XXXXXXX\", // Record key obtained from https://app.currents.dev, any value for Sorry Cypress\n  cloudServiceUrl: \"https://cy.currents.dev\", // Sorry Cypress users - the director service URL\n  // Additional headers for network requests, undefined by default\n  networkHeaders: {\n    \"User-Agent\": \"Custom\",\n    \"x-ms-blob-type\": \"BlockBlob\"\n  }\n  e2e: {\n    batchSize: 3, // orchestration batch size for e2e tests (Currents only, read below)\n  },\n  component: {\n    batchSize: 5, // orchestration batch size for component tests (Currents only, read below)\n  },\n};\n```\n\n### Configuration File Discovery\n\n`cypress-cloud` will search for a configuration file as follows:\n\n- if `--cloud-config-file \u003cstring\u003e` is defined, use its value\n\n  - use it as-is for absolute paths\n  - if it's a relative path, use the project's root location (defined with `-P --project` CLI option) as the base directory\n\n- otherwise, use the default filenames in the project's root location (defined with `-P --project` CLI option) in the following order:\n  - `currents.config.js`\n  - `currents.config.cjs`\n  - `currents.config.mjs`\n\nThe configuration file will be read using [`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) expression. Please make sure to use the correct syntax if you're using ESM modules (see the guide below).\n\n### Configuration Overrides\n\nYou can override the configuration values via environment variables:\n\n- `CURRENTS_API_URL` - sorry-cypress users - set the URL of your director service\n- `CURRENTS_PROJECT_ID` - set the `projectId`\n- `CURRENTS_RECORD_KEY` - cloud service record key\n\nThe configuration variables will resolve as follows:\n\n- the corresponding CLI flag or `run` function parameter, otherwise\n- environment variable if exist, otherwise\n- configuration file `currents.config.js|cjs|mjs` value, otherwise\n- the default value, otherwise throw\n\n## Batched Orchestration\n\nThis package uses its own orchestration and reporting protocol that is independent of cypress native implementation. The new [orchestration protocol](https://currents.dev/readme/integration-with-cypress/cypress-cloud#batched-orchestration) 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.\n\n## API\n\n### `run`\n\nRun Cypress tests programmatically. See [`./examples/webapp/scripts`](https://github.com/currents-dev/cypress-cloud/blob/main/examples/webapp/scripts) for examples.\n\n```ts\nrun(params: CurrentsRunAPI): Promise\u003cCypressCommandLine.CypressRunResult | undefined\u003e\n```\n\n- `params` - [`CurrentsRunAPI`](./packages/cypress-cloud/types.ts) list of params. It is an extended version of Cypress [Module API](https://docs.cypress.io/guides/guides/module-api)\n- return execution results as [`CypressCommandLine.CypressRunResult | undefined`](./packages/cypress-cloud/types.ts)\n\nExample:\n\n```ts\nimport { run } from \"cypress-cloud\";\n\nconst results = await run({\n  recordKey: \"some\",\n  reporter: \"junit\",\n  browser: \"chrome\",\n  config: {\n    baseUrl: \"http://localhost:8080\",\n    video: true,\n  },\n});\n```\n\n## Guides\n\n### Usage with `@cypress/grep`\n\nThe package is compatible with [`@cypress/grep`](https://www.npmjs.com/package/@cypress/grep). Make sure to run `require(\"@cypress/grep/src/plugin\")(config);` before `await currents(on, config);`, for example:\n\n```js\nsetupNodeEvents(on, config) {\n  require(\"cypress-terminal-report/src/installLogsPrinter\")(on);\n  require(\"@cypress/grep/src/plugin\")(config);\n  return currents(on, config);\n}\n```\n\nPlease refer to the [issue](https://github.com/currents-dev/cypress-cloud/issues/50#issuecomment-1645095284) for details.\n\n### Setup with existing plugins\n\n`cypress-cloud/plugin` needs access to certain environment variables that are injected into the `config` parameter of `setupNodeEvents(on, config)`.\n\nPlease make sure to preserve the original `config.env` parameters in case you are using additional plugins, e.g.:\n\n```js\nconst { defineConfig } = require(\"cypress\");\nconst { cloudPlugin } = require(\"cypress-cloud/plugin\");\n\nmodule.exports = defineConfig({\n  e2e: {\n    // ...\n    setupNodeEvents(on, config) {\n      // alternative: activate the plugin first\n      // cloudPlugin(on, config)\n      const enhancedConfig = {\n        env: {\n          // preserve the original env\n          ...config.env,\n          customVariable: \"value\",\n        },\n      };\n      return cloudPlugin(on, enhancedConfig);\n    },\n  },\n});\n```\n\nAs an alternative, you can activate the `cloudPlugin` first, and then implement the custom setup. Please contact our support if you have a complex plugin configuration to get assistance with the setup.\n\n### Spec files discovery\n\n`cypress-cloud` discovers the spec files using [`globby`](https://www.npmjs.com/package/globby) patterns according to the following logic:\n\n- if no `--spec` is provided, use the `specPattern` defined in `cypress.config.{jt}s`\n- if `--spec` flag is provided, use the intersection of `specPattern` and `--spec`\n- if no spec files were discovered, halt the execution and show a warning\n\nEnable the debug mode to troubleshoot files discovery: `DEBUG=currents:specs npx cypress-cloud ...`\n\n### Usage with ESM project\n\nFor ESM projects (`\"type\": \"module\"` in `package.json`) you can use one of the following formats:\n\n- `currents.config.cjs` - CommonJS formatted file\n- `currents.config.js` - ESM formatted file (i.e. no `require` statements)\n- `currents.config.mjs` - ESM formatted file (i.e. no `require` statements)\n\nAlso, make sure that your `cypress.config.js|mjs|cjs|ts` is formatted accordingly. See examples in [`./e2e`](./e2e) directory.\n\n## Troubleshooting\n\nEnable the debug mode by adding `--cloud-debug true | all | cypress | currents | commit-info` flag\n\n- `true | all` enable debug mode for all the tools\n- `cypress` activate debug mode for cypress only\n- `currents` activate the debug mode for currents only\n- `commit-info` activate the debug mode for git commit info only\n\n```sh\n# show all the debug information\nnpx cypress-cloud run ... --cloud-debug\n\n# show only currents related debug information\nnpx cypress-cloud run ... --cloud-debug currents,commit-info\n```\n\nCapture all the logs as a plain text file and share it with the support team for further troubleshooting.\n\n## Testing\n\n```sh\nnpm run test\n```\n\n\u003e 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.\n\n## Releasing\n\n### Beta channel\n\n```sh\ncd packages/cypress-cloud\nnpm run release -- --preRelease=beta \u0026\u0026 npm run release:npm -- -t beta\n```\n\n### Latest channel\n\n```sh\ncd packages/cypress-cloud\nnpm run release \u0026\u0026 npm run release:npm -- -t latest\n```\n\n### Localhost\n\nPublishing from `packages/cypress-cloud`:\n\n```sh\ndocker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio\nnpm adduser --registry http://localhost:4873\nnpm login --registry http://localhost:4873\nnpm_config_registry=http://localhost:4873  npm run release:npm -- --tag latest\n```\n\nUsing:\n\n```sh\nnpm install cypress-cloud --registry http://localhost:4873\n```\n\n## License\n\nGNU General Public License Version 3\n\nCopyright (C) 2023 Currents Software Inc https://currents.dev.\n\nThis is free software, and you are welcome to redistribute it under certain\nconditions. This program comes with no warranty. Parts of this program are MIT\nlicensed. Refer to the license for details\nhttps://github.com/currents-dev/cypress-cloud/blob/main/LICENSE.md\n\n## Disclaimer\n\nThis 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.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurrents-dev%2Fcypress-cloud-private","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurrents-dev%2Fcypress-cloud-private","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurrents-dev%2Fcypress-cloud-private/lists"}