chore(multi-domain): Throw errors for unsupported commands (#20729)

cli/types/cypress.d.ts

@@ -5459,6 +5459,21 @@ declare namespace Cypress {
     (action: 'task', tasks: Tasks): void
   }
 
+  interface CodeFrame {
+    frame: string
+    language: string
+    line: number
+    column: number
+    absoluteFile: string
+    originalFile: string
+    relativeFile: string
+  }
+
+  interface CypressError extends Error {
+    docsUrl?: string
+    codeFrame?: CodeFrame
+  }
+
   // for just a few events like "window:alert" it makes sense to allow passing cy.stub() or
   // a user callback function. Others probably only need a callback function.
 
@@ -5564,7 +5579,7 @@ declare namespace Cypress {
      *  This event exists because it's extremely useful for debugging purposes.
      * @see https://on.cypress.io/catalog-of-events#App-Events
      */
-    (action: 'fail', fn: (error: Error, mocha: Mocha.Runnable) => void): Cypress
+    (action: 'fail', fn: (error: CypressError, mocha: Mocha.Runnable) => void): Cypress
     /**
      * Fires whenever the viewport changes via a `cy.viewport()` or naturally when
      * Cypress resets the viewport to the default between tests. Useful for debugging purposes.

cli/types/tests/actions.ts

@@ -33,7 +33,7 @@ Cypress.on('url:changed', (url) => {
 })
 
 Cypress.on('fail', (error, mocha) => {
-  error // $ExpectType Error
+  error // $ExpectType CypressError
   mocha // $ExpectType Runnable
 })
 

packages/driver/cypress/integration/e2e/multi-domain/commands/multi_domain_network_requests.spec.ts

@@ -13,18 +13,4 @@ context.skip('multi-domain network requests', { experimentalSessionSupport: true
       })
     })
   })
-
-  it('.intercept()', () => {
-    cy.switchToDomain('http://foobar.com:3500', () => {
-      cy.intercept('POST', '/post-only', {
-        statusCode: 201,
-        body: 'Added',
-      }).as('mockRequest')
-
-      cy.get('#request').click()
-
-      cy.wait('@mockRequest')
-      cy.get('#result').should('contain', 'Added')
-    })
-  })
 })

packages/driver/cypress/integration/e2e/multi-domain/commands/multi_domain_screenshot.spec.ts

@@ -256,7 +256,6 @@ context('multi-domain screenshot', { experimentalSessionSupport: true }, () => {
         expect(err.name).to.eq('Error')
         expect(err.message).to.include('setTimeout error during screenshot')
         expect(err.message).to.include('The following error originated from your application code, not from Cypress.')
-        // @ts-ignore
         expect(err.docsUrl).to.deep.eq(['https://on.cypress.io/uncaught-exception-from-application'])
       })
 

packages/driver/cypress/integration/e2e/multi-domain/commands/multi_domain_session.spec.ts

@@ -1,34 +0,0 @@
-// @ts-ignore / session support is needed for visiting about:blank between tests
-// FIXME: CypressError: experimentalSessionSupport is not enabled.
-// You must enable the experimentalSessionSupport flag in order to use Cypress session commands
-// at throwIfNoSessionSupport(webpack:///../driver/src/cy/commands/sessions.ts?:287:76)
-// at session(webpack:///../driver/src/cy/commands/sessions.ts?:516:7)
-context.skip('multi-domain session', { experimentalSessionSupport: true }, () => {
-  before(() => {
-    cy.visit('/fixtures/multi-domain.html')
-    cy.get('a[data-cy="dom-link"]').click()
-  })
-
-  beforeEach(() => {
-    cy.switchToDomain('http://foobar.com:3500', () => {
-      cy.session('multi-domain', () => {
-        localStorage.setItem('foo', 'bar')
-      })
-    })
-
-    cy.visit('/fixtures/multi-domain.html')
-    cy.get('a[data-cy="dom-link"]').click()
-  })
-
-  it('verify new session', () => {
-    cy.switchToDomain('http://foobar.com:3500', () => {
-      expect(localStorage.getItem('foo')).to.equal('bar')
-    })
-  })
-
-  it('verify saved session', () => {
-    cy.switchToDomain('http://foobar.com:3500', () => {
-      expect(localStorage.getItem('foo')).to.equal('bar')
-    })
-  })
-})

packages/driver/cypress/integration/e2e/multi-domain/commands/multi_domain_unsupported_commands.spec.ts

@@ -5,9 +5,10 @@ context('multi-domain unsupported commands', { experimentalSessionSupport: true
     cy.get('a[data-cy="multi-domain-secondary-link"]').click()
   })
 
-  it('throws an error that the `cy.route()` method is deprecated and unsupported when attempted use is in multi-domain', (done) => {
+  it('cy.route() method is deprecated', (done) => {
     cy.on('fail', (err) => {
-      expect(err.message).to.equal('`cy.route()` has been deprecated and use is not supported in `cy.switchToDomain()`. Consider using `cy.intercept()` instead.')
+      expect(err.message).to.equal('`cy.route()` has been deprecated and use is not supported in the `cy.switchToDomain()` callback. Consider using `cy.intercept()` (outside of the callback) instead.')
+      expect(err.docsUrl).to.equal('https://on.cypress.io/intercept')
       done()
     })
 
@@ -16,9 +17,10 @@ context('multi-domain unsupported commands', { experimentalSessionSupport: true
     })
   })
 
-  it('throws an error that the `cy.server()` method is deprecated and unsupported when attempted use is in multi-domain', (done) => {
+  it('cy.server() method is deprecated', (done) => {
     cy.on('fail', (err) => {
-      expect(err.message).to.equal('`cy.server()` has been deprecated and use is not supported in `cy.switchToDomain()`. Consider using `cy.intercept()` instead.')
+      expect(err.message).to.equal('`cy.server()` has been deprecated and use is not supported in the `cy.switchToDomain()` callback. Consider using `cy.intercept()` (outside of the callback) instead.')
+      expect(err.docsUrl).to.equal('https://on.cypress.io/intercept')
       done()
     })
 
@@ -26,4 +28,40 @@ context('multi-domain unsupported commands', { experimentalSessionSupport: true
       cy.server()
     })
   })
+
+  it('cy.switchToDomain() is not yet supported', (done) => {
+    cy.on('fail', (err) => {
+      expect(err.message).to.equal('`cy.switchToDomain()` use is not currently supported in the `cy.switchToDomain()` callback, but is planned for a future release. Please 👍 the following issue and leave a comment with your use-case:')
+      expect(err.docsUrl).to.equal('https://on.cypress.io/github-issue/20718')
+      done()
+    })
+
+    cy.switchToDomain('http://foobar.com:3500', () => {
+      cy.switchToDomain('barbaz.com', () => {})
+    })
+  })
+
+  it('cy.intercept() is not supported', (done) => {
+    cy.on('fail', (err) => {
+      expect(err.message).to.equal('`cy.intercept()` use is not supported in the `cy.switchToDomain()` callback. Consider using it outside of the callback instead. Otherwise, please 👍 the following issue and leave a comment with your use-case:')
+      expect(err.docsUrl).to.equal('https://on.cypress.io/github-issue/20720')
+      done()
+    })
+
+    cy.switchToDomain('http://foobar.com:3500', () => {
+      cy.intercept('/foo')
+    })
+  })
+
+  it('cy.session() is not supported', (done) => {
+    cy.on('fail', (err) => {
+      expect(err.message).to.equal('`cy.session()` use is not supported in the `cy.switchToDomain()` callback. Consider using it outside of the callback instead. Otherwise, please 👍 the following issue and leave a comment with your use-case:')
+      expect(err.docsUrl).to.equal('https://on.cypress.io/github-issue/20721')
+      done()
+    })
+
+    cy.switchToDomain('http://foobar.com:3500', () => {
+      cy.session('/foo')
+    })
+  })
 })

packages/driver/cypress/integration/e2e/multi-domain/multi_domain_cypress_api.spec.ts

@@ -218,7 +218,8 @@ describe('multi-domain Cypress API', { experimentalSessionSupport: true }, () =>
   context('not supported', () => {
     it('throws an error when a user attempts to configure Cypress.Server.defaults() inside of multi-domain', (done) => {
       cy.on('fail', (err) => {
-        expect(err.message).to.equal('`Cypress.Server.*` has been deprecated and use is not supported in `cy.switchToDomain()`. Consider using `cy.intercept()` instead.')
+        expect(err.message).to.equal('`Cypress.Server.*` has been deprecated and use is not supported in the `cy.switchToDomain()` callback. Consider using `cy.intercept()` (outside of the callback) instead.')
+        expect(err.docsUrl).to.equal('https://on.cypress.io/intercept')
         done()
       })
 
@@ -229,7 +230,8 @@ describe('multi-domain Cypress API', { experimentalSessionSupport: true }, () =>
 
     it('throws an error when a user attempts to configure Cypress.Cookies.preserveOnce() inside of multi-domain', (done) => {
       cy.on('fail', (err) => {
-        expect(err.message).to.equal('`Cypress.Cookies.preserveOnce` use is not supported in `cy.switchToDomain()`. Consider using `cy.session()` instead.')
+        expect(err.message).to.equal('`Cypress.Cookies.preserveOnce` use is not supported in the `cy.switchToDomain()` callback. Consider using `cy.session()` (outside of the callback) instead.')
+        expect(err.docsUrl).to.equal('https://on.cypress.io/session')
         done()
       })
 

packages/driver/cypress/integration/e2e/multi-domain/multi_domain_uncaught_errors_spec.ts

@@ -37,7 +37,6 @@ describe('multi-domain - uncaught errors', () => {
         expect(err.message).to.include('sync error')
         expect(err.message).to.include('The following error originated from your application code, not from Cypress.')
         expect(err.message).to.not.include('https://on.cypress.io/uncaught-exception-from-application')
-        // @ts-ignore
         expect(err.docsUrl).to.deep.eq(['https://on.cypress.io/uncaught-exception-from-application'])
 
         // lastly, make sure the `uncaught:exception' handler is NOT called in the primary
@@ -75,7 +74,6 @@ describe('multi-domain - uncaught errors', () => {
         expect(err.message).to.include('sync error')
         expect(err.message).to.include('The following error originated from your application code, not from Cypress.')
         expect(err.message).to.not.include('https://on.cypress.io/uncaught-exception-from-application')
-        // @ts-ignore
         expect(err.docsUrl).to.deep.eq(['https://on.cypress.io/uncaught-exception-from-application'])
 
         done()
@@ -132,7 +130,6 @@ describe('multi-domain - uncaught errors', () => {
         expect(err.message).to.include('async error')
         expect(err.message).to.include('The following error originated from your application code, not from Cypress.')
         expect(err.message).to.not.include('https://on.cypress.io/uncaught-exception-from-application')
-        // @ts-ignore
         expect(err.docsUrl).to.deep.eq(['https://on.cypress.io/uncaught-exception-from-application'])
 
         expect(uncaughtExceptionSpy).not.to.be.called

packages/driver/src/cypress/error_messages.ts

@@ -1765,31 +1765,34 @@ export default {
       message: stripIndent`\
       ${cmd('switchToDomain')} could not serialize the thrown value. Please make sure the value being thrown is supported by the structured clone algorithm.`,
     },
-    // TODO: These deprecation warnings and forbidden use errors need to be audited before releasing multi-domain
-    route: {
-      unsupported: {
-        message: `${cmd('route')} has been deprecated and use is not supported in ${cmd('switchToDomain')}. Consider using ${cmd('intercept')} instead.`,
+    unsupported: {
+      route: {
+        message: `${cmd('route')} has been deprecated and use is not supported in the ${cmd('switchToDomain')} callback. Consider using ${cmd('intercept')} (outside of the callback) instead.`,
         docsUrl: 'https://on.cypress.io/intercept',
       },
-    },
-    server: {
-      unsupported: {
-        message: `${cmd('server')} has been deprecated and use is not supported in ${cmd('switchToDomain')}. Consider using ${cmd('intercept')} instead.`,
+      server: {
+        message: `${cmd('server')} has been deprecated and use is not supported in the ${cmd('switchToDomain')} callback. Consider using ${cmd('intercept')} (outside of the callback) instead.`,
         docsUrl: 'https://on.cypress.io/intercept',
       },
-    },
-    Server: {
-      unsupported: {
-        message: `\`Cypress.Server.*\` has been deprecated and use is not supported in ${cmd('switchToDomain')}. Consider using ${cmd('intercept')} instead.`,
+      Server: {
+        message: `\`Cypress.Server.*\` has been deprecated and use is not supported in the ${cmd('switchToDomain')} callback. Consider using ${cmd('intercept')} (outside of the callback) instead.`,
         docsUrl: 'https://on.cypress.io/intercept',
       },
-    },
-    Cookies: {
-      preserveOnce: {
-        unsupported: {
-          message: `\`Cypress.Cookies.preserveOnce\` use is not supported in ${cmd('switchToDomain')}. Consider using ${cmd('session')} instead.`,
-          docsUrl: 'https://on.cypress.io/session',
-        },
+      Cookies_preserveOnce: {
+        message: `\`Cypress.Cookies.preserveOnce\` use is not supported in the ${cmd('switchToDomain')} callback. Consider using ${cmd('session')} (outside of the callback) instead.`,
+        docsUrl: 'https://on.cypress.io/session',
+      },
+      switchToDomain: {
+        message: `${cmd('switchToDomain')} use is not currently supported in the ${cmd('switchToDomain')} callback, but is planned for a future release. Please 👍 the following issue and leave a comment with your use-case:`,
+        docsUrl: 'https://on.cypress.io/github-issue/20718',
+      },
+      intercept: {
+        message: `${cmd('intercept')} use is not supported in the ${cmd('switchToDomain')} callback. Consider using it outside of the callback instead. Otherwise, please 👍 the following issue and leave a comment with your use-case:`,
+        docsUrl: 'https://on.cypress.io/github-issue/20720',
+      },
+      session: {
+        message: `${cmd('session')} use is not supported in the ${cmd('switchToDomain')} callback. Consider using it outside of the callback instead. Otherwise, please 👍 the following issue and leave a comment with your use-case:`,
+        docsUrl: 'https://on.cypress.io/github-issue/20721',
       },
     },
   },

packages/driver/src/multi-domain/unsupported_apis.ts

@@ -2,18 +2,30 @@ import type { $Cy } from '../cypress/cy'
 import $errUtils from '../cypress/error_utils'
 
 export const handleUnsupportedAPIs = (Cypress: Cypress.Cypress, cy: $Cy) => {
-  // outlaw the use of `route` and `server` within the multi-domain context and Cypress.Server.* configurations
+  // The following commands/methods are not supported within the `switchToDomain`
+  // callback since they are deprecated
   // @ts-ignore
-  cy.route = () => $errUtils.throwErrByPath('switchToDomain.route.unsupported')
+  cy.route = () => $errUtils.throwErrByPath('switchToDomain.unsupported.route')
   // @ts-ignore
-  cy.server = () => $errUtils.throwErrByPath('switchToDomain.server.unsupported')
+  cy.server = () => $errUtils.throwErrByPath('switchToDomain.unsupported.server')
   Cypress.Server = new Proxy(Cypress.Server, {
-    get: () => $errUtils.throwErrByPath('switchToDomain.Server.unsupported'),
+    get: () => $errUtils.throwErrByPath('switchToDomain.unsupported.Server'),
     // @ts-ignore
-    set: () => $errUtils.throwErrByPath('switchToDomain.Server.unsupported'),
+    set: () => $errUtils.throwErrByPath('switchToDomain.unsupported.Server'),
   })
 
-  // outlaw the use of Cypress.Cookies.* configurations, but allow other cy cookies methods to be used
   // @ts-ignore
-  Cypress.Cookies.preserveOnce = () => $errUtils.throwErrByPath('switchToDomain.Cookies.preserveOnce.unsupported')
+  Cypress.Cookies.preserveOnce = () => $errUtils.throwErrByPath('switchToDomain.unsupported.Cookies_preserveOnce')
+
+  // Nested `switchToDomain` is not currently supported, but will be in the future
+  // @ts-ignore
+  cy.switchToDomain = () => $errUtils.throwErrByPath('switchToDomain.unsupported.switchToDomain')
+
+  // `intercept` and `session` are not supported within the `switchToDomain`
+  // callback, but can be used outside of it for the same effect. It's unlikely
+  // they will ever be supported unless we discover uses-cases that require it
+  // @ts-ignore
+  cy.intercept = () => $errUtils.throwErrByPath('switchToDomain.unsupported.intercept')
+  // @ts-ignore
+  cy.session = () => $errUtils.throwErrByPath('switchToDomain.unsupported.session')
 }