Merge branch 'develop' into electron-34

Author: cacieprins

cli/CHANGELOG.md

@@ -10,9 +10,11 @@ _Released 5/6/2025 (PENDING)_
 **Bugfixes:**
 
 - Fixed an issue where the configuration setting `trashAssetsBeforeRuns=false` was ignored for assets in the `videosFolder`. These assets were incorrectly deleted before running tests with `cypress run`. Addresses [#8280](https://github.com/cypress-io/cypress/issues/8280).
+- Fixed a potential hang condition when navigating to `about:blank`. Addressed in [#31634](https://github.com/cypress-io/cypress/pull/31634).
 
 **Misc:**
 
+- The Assertions menu when you right click in `experimentalStudio` tests now displays in dark mode. Addresses [#10621](https://github.com/cypress-io/cypress-services/issues/10621). Addressed in [#31598](https://github.com/cypress-io/cypress/pull/31598).
 - The URL in the Cypress App no longer displays a white background when the URL is loading. Fixes [#31556](https://github.com/cypress-io/cypress/issues/31556).
 
 **Dependency Updates:**

guides/README.md

@@ -19,7 +19,9 @@ For general contributor information, check out [`CONTRIBUTING.md`](../CONTRIBUTI
 * [Error handling](./error-handling.md)
 * [GraphQL Subscriptions - Overview and Test Guide](./graphql-subscriptions.md)
 * [Patching packages](./patch-package.md)
+* [Protocol development](./protocol-development.md)
 * [Release process](./release-process.md)
+* [Studio development](./studio-development.md)
 * [Testing other projects](./testing-other-projects.md)
 * [Testing strategy and style guide (draft)](./testing-strategy-and-styleguide.md)
 * [Writing cross-platform JavaScript](./writing-cross-platform-javascript.md)

guides/studio-development.md

@@ -1,22 +1,33 @@
 # Studio Development
 
-In production, the code used to facilitate Studio functionality will be retrieved from the Cloud. While Studio is still in its early stages it is hidden behind an environment variable: `CYPRESS_ENABLE_CLOUD_STUDIO`. Set this environment variable to `true` if you want to run Cypress against the deployed version of studio code:
+In production, the code used to facilitate Studio functionality will be retrieved from the Cloud. While Studio is still in its early stages it is hidden behind an environment variable: `CYPRESS_ENABLE_CLOUD_STUDIO` but can also be run against local cloud Studio code via the environment variable: `CYPRESS_LOCAL_STUDIO_PATH`.
 
-```sh
-CYPRESS_ENABLE_CLOUD_STUDIO=true yarn cypress:open
-```
-
-If you want to run against locally developed Studio code:
+To run against locally developed Studio:
 
 - Clone the `cypress-services` repo (this requires that you be a member of the Cypress organization)
   - Run `yarn`
-  - Run `yarn watch` in `app/studio`
-- Set `CYPRESS_LOCAL_STUDIO_PATH` to the path to the `cypress-services/app/studio/dist/development` directory
+  - Run `yarn watch` in `app/packages/studio`
+- Set:
+  - `CYPRESS_INTERNAL_ENV=<environment>` (e.g. `staging` or `production` if you want to hit those deployments of `cypress-services` or `development` if you want to hit a locally running version of `cypress-services`)
+  - `CYPRESS_LOCAL_STUDIO_PATH` to the path to the `cypress-services/app/packages/studio/dist/development` directory
+ 
+To run against a deployed version of studio:
+
+- Set:
+  - `CYPRESS_INTERNAL_ENV=<environment>` (e.g. `staging` or `production` if you want to hit those deployments of `cypress-services` or `development` if you want to hit a locally running version of `cypress-services`)
+  - `CYPRESS_ENABLE_CLOUD_STUDIO=true`
+
+Regardless of running against local or deployed studio:
+
 - Clone the `cypress` repo
   - Run `yarn`
   - Run `yarn cypress:open`
- 
-Note: When using the `CYPRESS_LOCAL_STUDIO_PATH` environment variable, we bypass our error reporting and instead throw the exception immediately. The purpose of this is to try and surface issues immediately during local development.
+  - Log In to the Cloud via the App
+  - Ensure the project has been setup in the `Cypress (staging)` if in staging environment or `Cypress Internal Org` if in production environment and has a `projectId` that represents that. If developing against locally running `cypress-services`, ensure that the project has the feature `studio-ai` enabled for it.
+  - Open a project that has `experimentalStudio: true` set in the `e2e` config of the `cypress.config.js|ts` file.
+  - Click to 'Add Commands to Test' after hovering over a test command.
+
+Note: When using the `CYPRESS_LOCAL_STUDIO_PATH` environment variable or when running the Cypress app via the locally cloned repository, we bypass our error reporting and instead log errors to the browser or node console.
 
 ## Types
 
@@ -31,3 +42,59 @@ or to reference a local `cypress_services` repo:
 ```sh
 CYPRESS_LOCAL_STUDIO_PATH=<path-to-cypress-services/app/studio/dist/development-directory> yarn gulp downloadStudioTypes
 ```
+
+## Testing
+
+### Unit/Component Testing
+
+The code that supports cloud Studio and lives in the `cypress` monorepo is unit and component tested in a similar fashion to the rest of the code in the repo. See the [contributing guide](https://github.com/cypress-io/cypress/blob/ad353fcc0f7fdc51b8e624a2a1ef4e76ef9400a0/CONTRIBUTING.md?plain=1#L366) for more specifics.
+
+The code that supports cloud Studio and lives in the `cypress-services` monorepo has unit and component tests that live alongside the code in that monorepo.
+
+### Cypress in Cypress Testing
+
+Several helpers are provided to facilitate testing cloud Studio using Cypress in Cypress tests. The [helper file](https://github.com/cypress-io/cypress/blob/ad353fcc0f7fdc51b8e624a2a1ef4e76ef9400a0/packages/app/cypress/e2e/studio/helper.ts) provides a method, `launchStudio` that:
+
+1. Loads a project (by default [`experimental-studio`](https://github.com/cypress-io/cypress/tree/develop/system-tests/projects/experimental-studio)).
+2. Navigates to the appropriate spec (by default `specName.cy.js`).
+3. Enters Studio either by creating a new test or entering from an existing test via the `createNewTest` parameter
+4. Waits for the test to finish executing again in Studio mode.
+
+The above steps actually download the studio code from the cloud and use it for the test. Note that `experimental-studio` is set up to be a `canary` project so it will always get the latest and greatest of the cloud Studio code, whether or not it has been fully promoted to production. Note that this means that if you are writing Cypress in Cypress tests that depend on new functionality delivered from the cloud, the Cypress in Cypress tests cannot be merged until the code lands and is built in the cloud. Local development is still possible however by setting `process.env.CYPRESS_LOCAL_STUDIO_PATH` to your local studio path where we enable studio [here](https://github.com/cypress-io/cypress/blob/develop/packages/frontend-shared/cypress/e2e/e2ePluginSetup.ts#L424).
+
+In order to properly engage with Studio AI, we choose to simulate the cloud interactions that enable it via something like:
+
+```js
+cy.mockNodeCloudRequest({
+  url: '/studio/testgen/n69px6/enabled',
+  method: 'get',
+  body: { enabled: true },
+})
+```
+
+To ensure that we get the same results from our Studio AI calls every time, we simulate them via something like:
+
+```js
+const aiOutput = 'cy.get(\'button\').should(\'have.text\', \'Increment\')'
+cy.mockNodeCloudStreamingRequest({
+  url: '/studio/testgen/n69px6/generate',
+  method: 'post',
+  body: { recommendations: [{ content: aiOutput }] },
+})
+```
+
+The above two helpers actually mock out the Node requests so we still test the interface between the browser and node with these tests.
+
+Also, since protocol does not work properly on the inner Cypress of Cypress in Cypress tests, we choose to create a dummy protocol which means we need to provide a simulated CDP full snapshot that will be sent to AI via something like:
+
+```js
+cy.mockStudioFullSnapshot({
+  id: 1,
+  nodeType: 1,
+  nodeName: 'div',
+  localName: 'div',
+  nodeValue: 'div',
+  children: [],
+  shadowRoots: [],
+})
+```

packages/app/cypress/e2e/studio/studio.cy.ts

@@ -167,6 +167,74 @@ describe('studio functionality', () => {
 
       cy.percySnapshot()
     })
+
+    it('opens a cloud studio session with AI enabled', () => {
+      cy.mockNodeCloudRequest({
+        url: '/studio/testgen/n69px6/enabled',
+        method: 'get',
+        body: { enabled: true },
+      })
+
+      const aiOutput = 'cy.get(\'button\').should(\'have.text\', \'Increment\')'
+
+      cy.mockNodeCloudStreamingRequest({
+        url: '/studio/testgen/n69px6/generate',
+        method: 'post',
+        body: { recommendations: [{ content: aiOutput }] },
+      })
+
+      cy.mockStudioFullSnapshot({
+        id: 1,
+        nodeType: 1,
+        nodeName: 'div',
+        localName: 'div',
+        nodeValue: 'div',
+        children: [],
+        shadowRoots: [],
+      })
+
+      const deferred = pDefer()
+
+      loadProjectAndRunSpec({ enableCloudStudio: true })
+
+      cy.findByTestId('studio-panel').should('not.exist')
+
+      cy.intercept('/cypress/e2e/index.html', () => {
+        // wait for the promise to resolve before responding
+        // this will ensure the studio panel is loaded before the test finishes
+        return deferred.promise
+      }).as('indexHtml')
+
+      cy.contains('visits a basic html page')
+      .closest('.runnable-wrapper')
+      .findByTestId('launch-studio')
+      .click()
+
+      // regular studio is not loaded until after the test finishes
+      cy.get('[data-cy="hook-name-studio commands"]').should('not.exist')
+      // cloud studio is loaded immediately
+      cy.findByTestId('studio-panel').then(() => {
+        // check for the loading panel from the app first
+        cy.get('[data-cy="loading-studio-panel"]').should('be.visible')
+        // we've verified the studio panel is loaded, now resolve the promise so the test can finish
+        deferred.resolve()
+      })
+
+      cy.wait('@indexHtml')
+
+      // Studio re-executes spec before waiting for commands - wait for the spec to finish executing.
+      cy.waitForSpecToFinish()
+
+      // Verify the studio panel is still open
+      cy.findByTestId('studio-panel')
+      cy.get('[data-cy="hook-name-studio commands"]')
+
+      // Verify that AI is enabled
+      cy.get('[data-cy="ai-status-text"]').should('contain.text', 'Enabled')
+
+      // Verify that the AI output is correct
+      cy.get('[data-cy="studio-ai-output-textarea"]').should('contain.text', aiOutput)
+    })
   })
 
   it('updates an existing test with an action', () => {

packages/app/package.json

@@ -24,7 +24,7 @@
   "devDependencies": {
     "@cypress-design/icon-registry": "^1.5.1",
     "@cypress-design/vue-button": "^1.6.0",
-    "@cypress-design/vue-icon": "^1.6.0",
+    "@cypress-design/vue-icon": "^1.18.0",
     "@cypress-design/vue-spinner": "^1.0.0",
     "@cypress-design/vue-statusicon": "^1.0.0",
     "@cypress-design/vue-tabs": "^1.2.2",

packages/app/src/runner/aut-iframe.ts

@@ -129,8 +129,6 @@ export class AutIframe {
         return
       }
 
-      this.$iframe[0].src = 'about:blank'
-
       this.$iframe.one('load', () => {
         if (testIsolation) {
           this._showTestIsolationBlankPage()
@@ -140,6 +138,8 @@ export class AutIframe {
 
         resolve()
       })
+
+      this.$iframe[0].src = 'about:blank'
     })
   }
 

packages/app/src/runner/dom.cy.tsx

@@ -0,0 +1,58 @@
+import { getOrCreateHelperDom } from './dom'
+
+describe('dom utilities', () => {
+  describe('getOrCreateHelperDom', () => {
+    let body: HTMLBodyElement
+    const className = 'test-helper'
+    const css = 'test-css'
+
+    beforeEach(() => {
+      // Create a fresh body element for each test
+      body = document.createElement('body')
+      document.body = body
+    })
+
+    afterEach(() => {
+      // Clean up after each test
+      const containers = body.querySelectorAll(`.${className}`)
+
+      containers.forEach((container) => container.remove())
+    })
+
+    it('should create new helper DOM elements when none exist', () => {
+      const result = getOrCreateHelperDom({ body, className, css })
+
+      // Verify container was created
+      expect(result.container).to.exist
+      expect(result.container.classList.contains(className)).to.be.true
+      expect(result.container.style.all).to.equal('initial')
+      expect(result.container.style.position).to.equal('static')
+
+      // Verify shadow root was created
+      expect(result.shadowRoot).to.exist
+      expect(result.shadowRoot!.mode).to.equal('open')
+
+      // Verify vue container was created
+      expect(result.vueContainer).to.exist
+      expect(result.vueContainer.classList.contains('vue-container')).to.be.true
+
+      // Verify style was added
+      const style = result.shadowRoot!.querySelector('style')
+
+      expect(style).to.exist
+      expect(style!.innerHTML).to.equal(css)
+    })
+
+    it('should return existing helper DOM elements when they exist', () => {
+      // First call to create elements
+      const firstResult = getOrCreateHelperDom({ body, className, css })
+
+      // Second call to get existing elements
+      const secondResult = getOrCreateHelperDom({ body, className, css })
+
+      // Verify we got the same elements back
+      expect(secondResult.container).to.equal(firstResult.container)
+      expect(secondResult.vueContainer).to.equal(firstResult.vueContainer)
+    })
+  })
+})

packages/app/src/runner/dom.ts

@@ -30,6 +30,8 @@ export function getOrCreateHelperDom ({ body, className, css }) {
 
   container.classList.add(className)
 
+  // NOTE: This is needed to prevent the container from inheriting styles from the body of the AUT
+  container.style.all = 'initial'
   container.style.position = 'static'
 
   body.appendChild(container)