Merge branch 'main' into dependabot/npm_and_yarn/semver-5.7.2

.github/ISSUE_TEMPLATE/1.bug.yaml

@@ -3,16 +3,31 @@ description: Create a report to help us improve cypress-cloud
 labels: bug
 
 body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Before Opening a New Issue
+
+        Thank you for taking the time to open an issue!
+
+        `cypress-cloud` runs on various environments with different setups and configurations, we have to ask you to provide more information about your specific setup, otherwise we won't be able to help you.
+
+        Here are a few resources that can help you:
+
+        - [`cypress-cloud` Documentation](https://currents.dev/readme/integration-with-cypress) 
+        - [Troubleshooting Guide](https://currents.dev/readme/integration-with-cypress/troubleshooting) 
+        - [Common Configuration Pitfalls](https://github.com/currents-dev/cypress-cloud#setup-with-existing-plugins)
+
   - type: checkboxes
     attributes:
       label: |
-        Before opening, please confirm:
+        Please confirm
       options:
         - label: I have searched for [duplicate or closed issues](https://github.com/currents-dev/cypress-cloud/issues) and [discussions](https://github.com/currents-dev/cypress-cloud/discussions).
           required: true
-        - label: I have done my best to include a minimal, self-contained set of instructions for consistently reproducing the issue.
+        - label: I will include a minimal, self-contained set of instructions for consistently reproducing the issue.
           required: true
-        - label: I acknowledge that I will attach a **full debug log**, otherwise the issue will be closed with no response.
+        - label: I will attach a **full debug log**, otherwise the issue will be closed with no response.
           required: true
 
   - type: markdown
@@ -23,9 +38,9 @@ body:
     attributes:
       label: Environment information
       description: |
-        Please run the following command inside your project and copy/paste the output below.
+        We need to know what package versions you're using. Please run the following command inside your project and copy/paste the output below.
 
-         **👉🏻 Run the command in the right environment 👈🏻, e.g. if the problem is in CI environment, run it in the CI environment.
+         **👉🏻 Run the command in the right environment 👈🏻**, e.g. if the problem is in CI environment, run it in the CI environment.
 
         ```
         npx envinfo --system --binaries --browsers --npmPackages --duplicates --npmGlobalPackages
@@ -62,10 +77,10 @@ body:
 
   - type: textarea
     attributes:
-      label: Command and Setup
+      label: Setup and Command
       description: |
-        - The exact command or code snippet 
-        - Your cloud provider or sorry-cypress setup details
+        - Your `cypress.config.js` file, including standalone plugins configuration.
+        - The exact command or code snippet used to run the tests.
 
     validations:
       required: true
@@ -74,17 +89,18 @@ body:
     attributes:
       label: Full log and debug output
       description: |
-        Run in debug mode to provide more info - error messages and stack traces.
+        Enable the [debug mode](https://currents.dev/readme/integration-with-cypress/troubleshooting#enabling-debug-mode-for-cypress-cloud-1.9.0+) to provide more info - error messages and stack traces.
 
-        - **👉🏻 Include the full log 👈🏻 - starting from running the command till receiving an error.**
+        - Follow [the guide to enable debug mode](https://currents.dev/readme/integration-with-cypress/troubleshooting#enabling-debug-mode-for-cypress-cloud-1.9.0+)
+        - **👉🏻 Include the full log 👈🏻** - starting from running the command till receiving an error.
         - Attach a link / file for long outputs.
 
         Example:
 
-        - Linux: `DEBUG=currents:*,cypress:* cypress-cloud run ...`
-        - Windows: `cmd /V /C "set DEBUG=currents:*,cypress:* && cypress-cloud run ..."`
+        - `npx cypress-cloud run ... --cloud-debug`
+
+        **Remove any sensitive data.**
 
-        **Be sure to remove any sensitive data.**
       value: |
         <details>
 

.github/README.md

@@ -16,6 +16,33 @@ Integrate Cypress with alternative cloud services like Currents or Sorry Cypress
 
 </p>
 
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Setup](#setup)
+- [Usage](#usage)
+- [Example](#example)
+- [Configuration](#configuration)
+  - [Configuration File Discovery](#configuration-file-discovery)
+  - [Configuration Overrides](#configuration-overrides)
+- [Batched Orchestration](#batched-orchestration)
+- [API](#api)
+  - [`run`](#run)
+- [Guides](#guides)
+  - [Usage with `@cypress/grep`](#usage-with-cypressgrep)
+  - [Setup with existing plugins](#setup-with-existing-plugins)
+    - [Preserving `config.env` values](#preserving-configenv-values)
+    - [Chaining `config`](#chaining-config)
+    - [Event callbacks for multiple plugins](#event-callbacks-for-multiple-plugins)
+- [Spec files discovery](#spec-files-discovery)
+- [Usage with ESM project](#usage-with-esm-project)
+- [Troubleshooting](#troubleshooting)
+- [Testing](#testing)
+- [Releasing](#releasing)
+  - [Beta channel](#beta-channel)
+  - [Latest channel](#latest-channel)
+  - [Localhost](#localhost)
+
 ## Requirements
 
 - Cypress version 10+
@@ -44,14 +71,17 @@ module.exports = {
 
 Add `cypress-cloud/plugin` to `cypress.config.{js|ts|mjs}`
 
-```js
+```ts
 // cypress.config.js
-const { defineConfig } = require("cypress");
-const { cloudPlugin } = require("cypress-cloud/plugin");
-module.exports = defineConfig({
+import { defineConfig } from "cypress";
+import { cloudPlugin } from "cypress-cloud/plugin";
+
+export default defineConfig({
   e2e: {
-    setupNodeEvents(on, config) {
-      return cloudPlugin(on, config);
+    video: true; // enable video for cypress@13+
+    async setupNodeEvents(on, config) {
+      const result = await cloudPlugin(on, config);
+      return result;
     },
   },
 });
@@ -60,7 +90,7 @@ module.exports = defineConfig({
 Add `cypress-cloud/support` to Cypress Support file (matching your test type - e2e or component, or both)
 
 ```ts
-import `cypress-cloud/support`
+import "cypress-cloud/support";
 ```
 
 ## Usage
@@ -89,7 +119,7 @@ module.exports = {
   networkHeaders: {
     "User-Agent": "Custom",
     "x-ms-blob-type": "BlockBlob"
-  }
+  },
   e2e: {
     batchSize: 3, // orchestration batch size for e2e tests (Currents only, read below)
   },
@@ -132,7 +162,7 @@ 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](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.
+This 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](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.
 
 ## API
 
@@ -167,48 +197,108 @@ const results = await run({
 
 ### Usage with `@cypress/grep`
 
-The 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:
+The package is compatible with [`@cypress/grep`](https://www.npmjs.com/package/@cypress/grep).
 
-```js
-setupNodeEvents(on, config) {
-  require("cypress-terminal-report/src/installLogsPrinter")(on);
-  require("@cypress/grep/src/plugin")(config);
-  return currents(on, config);
-}
+`@cypress/grep` modifies cypress configuration and alters `specPattern` property. Install `@cypress/grep` **before** `cypress-cloud/plugin` to apply the modified configuration. For example:
+
+```ts
+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](https://github.com/currents-dev/cypress-cloud/issues/50#issuecomment-1645095284) for details.
 
 ### Setup with existing plugins
 
-`cypress-cloud/plugin` needs access to certain environment variables that are injected into the `config` parameter of `setupNodeEvents(on, config)`.
+#### Preserving `config.env` values
 
-Please make sure to preserve the original `config.env` parameters in case you are using additional plugins, e.g.:
+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:
 
-```js
-const { defineConfig } = require("cypress");
-const { cloudPlugin } = require("cypress-cloud/plugin");
+```ts
+import { defineConfig } from "cypress";
+import { cloudPlugin } from "cypress-cloud/plugin";
 
-module.exports = defineConfig({
+export default defineConfig({
   e2e: {
     // ...
-    setupNodeEvents(on, config) {
-      // alternative: activate the plugin first
-      // cloudPlugin(on, config)
+    async setupNodeEvents(on, config) {
       const enhancedConfig = {
         env: {
-          // preserve the original env
-          ...config.env,
+          ...config.env, // 👈🏻 preserve the original env
           customVariable: "value",
         },
       };
-      return cloudPlugin(on, enhancedConfig);
+      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.:
+
+```ts
+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;
     },
   },
 });
 ```
 
-As 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.
+#### 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](https://github.com/cypress-io/cypress/issues/22428)). 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:
+
+- https://github.com/bahmutov/cypress-on-fix
+- https://github.com/elaichenkov/cypress-plugin-init
+
+For example:
+
+```ts
+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
 

.github/workflows/e2e-exports.yml

@@ -12,15 +12,15 @@ jobs:
 
     strategy:
       matrix:
-        node-version: ["18", "16", "14"]
+        node-version: ["18", "20"]
 
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: Install npm (node14)
+      - name: Install npm
         run: npm install -g npm@latest
 
       - name: Install dependencies

CHANGELOG.md

@@ -1,5 +1,12 @@
 
 
+## [1.9.6](https://github.com/currents-dev/cypress-cloud/compare/v1.9.5...v1.9.6) (2023-09-19)
+
+
+### Bug Fixes
+
+* add post-run warnings ([#180](https://github.com/currents-dev/cypress-cloud/issues/180)) [CSR-601] ([e8d9354](https://github.com/currents-dev/cypress-cloud/commit/e8d93540d1aefb1235c0d478f4b39920d3267b9e))
+
 ## [1.9.5](https://github.com/currents-dev/cypress-cloud/compare/v1.9.4...v1.9.5) (2023-09-13)
 
 

examples/webapp/cypress.config.ts

@@ -1,5 +1,7 @@
+import grepPlugin from "@cypress/grep/src/plugin";
 import { defineConfig } from "cypress";
-import currents from "cypress-cloud/plugin";
+import { cloudPlugin } from "cypress-cloud/plugin";
+import patchCypressOn from "cypress-on-fix";
 
 module.exports = defineConfig({
   e2e: {
@@ -10,17 +12,19 @@ module.exports = defineConfig({
     videoUploadOnPasses: false,
     supportFile: "cypress/support/e2e.ts",
     specPattern: "cypress/*/**/*.spec.js",
-    setupNodeEvents(on, config) {
-      require("@cypress/grep/src/plugin")(config);
-      require("cypress-terminal-report/src/installLogsPrinter")(on);
-      return currents(on, config);
+    async setupNodeEvents(cyOn, config) {
+      const on = patchCypressOn(cyOn);
+      grepPlugin(config);
+      const result = await cloudPlugin(on, config);
+      return result;
     },
   },
 
   component: {
     specPattern: ["pages/__tests__/*.spec.tsx"],
-    setupNodeEvents(on, config) {
-      return currents(on, config);
+    async setupNodeEvents(on, config) {
+      const result = await cloudPlugin(on, config);
+      return result;
     },
     devServer: {
       framework: "next",

examples/webapp/cypress/support/e2e.ts

@@ -1,5 +1,4 @@
 import registerCypressGrep from "@cypress/grep/src/support";
-require("cypress-terminal-report/src/installLogsCollector")();
 require("cypress-cloud/support");
 require("./commands");
 

examples/webapp/package.json

@@ -12,6 +12,7 @@
   "dependencies": {
     "cypress": "^12.6.0",
     "cypress-cloud": "*",
+    "cypress-on-fix": "^1.0.2",
     "cypress-terminal-report": "^5.3.3",
     "next": "^13.2.1",
     "react": "^18.2.0",