fix: Improve error message when .shadow() subject is not a shadow host (#8538)

packages/driver/cypress/integration/commands/querying_shadow_dom_spec.js

@@ -134,6 +134,17 @@ describe('src/cy/commands/querying - shadow dom', () => {
       })
     })
 
+    it('has a custom error message if it cannot find a root', (done) => {
+      cy.on('fail', (err) => {
+        expect(err.message).to.equal(`Timed out retrying: Expected the subject to host a shadow root, but never found it.`)
+        expect(err.docsUrl).to.equal('https://on.cypress.io/shadow')
+
+        done()
+      })
+
+      cy.get('#non-shadow-element').shadow({ timeout: 0 })
+    })
+
     describe('.log', () => {
       beforeEach(function () {
         cy.on('log:added', (attrs, log) => {

packages/driver/src/cy/commands/querying.js

@@ -664,6 +664,16 @@ module.exports = (Commands, Cypress, cy, state) => {
 
         return cy.verifyUpcomingAssertions($el, options, {
           onRetry: getShadowRoots,
+          onFail (err) {
+            if (err.type !== 'existence') {
+              return
+            }
+
+            const { message, docsUrl } = $errUtils.cypressErrByPath('shadow.no_shadow_root')
+
+            err.message = message
+            err.docsUrl = docsUrl
+          },
         })
       }
 

packages/driver/src/cypress/error_messages.js

@@ -904,7 +904,7 @@ module.exports = {
     `,
     hook_registered_late: stripIndent`\
     Cypress detected you registered a(n) \`{{hookTitle}}\` hook while a test was running (possibly a hook nested inside another hook). All hooks must be registered before a test begins executing.
-    
+
     Move the \`{{hookTitle}}\` into a suite callback or the global scope.
     `,
 
@@ -1478,6 +1478,13 @@ module.exports = {
     },
   },
 
+  shadow: {
+    no_shadow_root: {
+      message: 'Expected the subject to host a shadow root, but never found it.',
+      docsUrl: 'https://on.cypress.io/shadow',
+    },
+  },
+
   should: {
     chainer_not_found: 'The chainer `{{chainer}}` was not found. Could not build assertion.',
     language_chainer: {