fix(driver): preserve literal selectors in diagnostics

Author: lucasgontijopacto

packages/driver/src/cypress/timeout_diagnostics.ts

@@ -1,12 +1,10 @@
 /**
  * Timeout Diagnostics - Smart suggestions for timeout errors
- * 
+ *
  * This module provides contextual diagnostics and actionable suggestions
  * when commands timeout, helping developers quickly identify and fix issues.
  */
 
-import _ from 'lodash'
-
 interface TimeoutContext {
   command: string
   selector?: string
@@ -32,7 +30,7 @@ export class TimeoutDiagnostics {
     dynamicContent: /loading|spinner|skeleton|placeholder/i,
     asyncLoad: /fetch|api|graphql|ajax/i,
     animation: /fade|slide|animate|transition/i,
-    
+
     // Network patterns
     slowNetwork: 3000, // threshold in ms
     manyRequests: 5,
@@ -41,7 +39,7 @@ export class TimeoutDiagnostics {
   /**
    * Generate diagnostic suggestions based on timeout context
    */
-  static analyze(context: TimeoutContext): DiagnosticSuggestion[] {
+  static analyze (context: TimeoutContext): DiagnosticSuggestion[] {
     const suggestions: DiagnosticSuggestion[] = []
 
     // Check for common selector issues
@@ -72,13 +70,13 @@ export class TimeoutDiagnostics {
     return suggestions
   }
 
-  private static analyzeSelectorIssues(context: TimeoutContext): DiagnosticSuggestion[] {
+  private static analyzeSelectorIssues (context: TimeoutContext): DiagnosticSuggestion[] {
     const suggestions: DiagnosticSuggestion[] = []
     const { selector = '', command } = context
 
     // Check for dynamic content indicators
     if (this.COMMON_PATTERNS.dynamicContent.test(selector)) {
-      const escapedSelector = selector.replace(/'/g, "\\'");
+      const escapedSelector = this.escapeSelector(selector)
 
       suggestions.push({
         reason: 'The selector appears to target dynamic/loading content that may not be ready yet',
@@ -94,8 +92,8 @@ export class TimeoutDiagnostics {
 
     // Check for potentially incorrect selectors
     if (selector.includes(' ') && !selector.includes('[') && command === 'get') {
-      const escapedFirst = selector.split(' ')[0].replace(/'/g, "\\'");
-      const escapedRest = selector.split(' ').slice(1).join(' ').replace(/'/g, "\\'");
+      const escapedFirst = this.escapeSelector(selector.split(' ')[0])
+      const escapedRest = this.escapeSelector(selector.split(' ').slice(1).join(' '))
 
       suggestions.push({
         reason: 'Complex selector detected - might be fragile or incorrect',
@@ -109,24 +107,27 @@ export class TimeoutDiagnostics {
     }
 
     // Check for ID selectors that might be dynamic
-    if (selector.startsWith('#') && /\d{3,}/.test(selector)) {
-      const prefix = selector.split(/\d/)[0];
-      const escapedPrefix = prefix.replace(/'/g, "\\'");
-
-      suggestions.push({
-        reason: 'Selector uses an ID with numbers - might be dynamically generated',
-        suggestions: [
-          'Dynamic IDs change between sessions and will cause flaky tests',
-          'Use a data-cy attribute or a more stable selector instead',
-          `If the ID is dynamic, use a partial match: cy.get('[id^="${escapedPrefix}"]').first()`,
-        ],
-      })
+    if (selector.startsWith('#')) {
+      const prefixMatch = selector.match(/^#([^\d]+)\d{3,}/)
+
+      if (prefixMatch) {
+        const escapedPrefix = this.escapeSelector(prefixMatch[1])
+
+        suggestions.push({
+          reason: 'Selector uses an ID with numbers - might be dynamically generated',
+          suggestions: [
+            'Dynamic IDs change between sessions and will cause flaky tests',
+            'Use a data-cy attribute or a more stable selector instead',
+              `If the ID is dynamic, use a partial match: cy.get('[id^="${escapedPrefix}"]').first()`,
+          ],
+        })
+      }
     }
 
     return suggestions
   }
 
-  private static analyzeNetworkIssues(context: TimeoutContext): DiagnosticSuggestion[] {
+  private static analyzeNetworkIssues (context: TimeoutContext): DiagnosticSuggestion[] {
     const suggestions: DiagnosticSuggestion[] = []
     const { networkRequests = 0, timeout } = context
 
@@ -161,7 +162,7 @@ export class TimeoutDiagnostics {
     return suggestions
   }
 
-  private static analyzeAnimationIssues(context: TimeoutContext): DiagnosticSuggestion[] {
+  private static analyzeAnimationIssues (context: TimeoutContext): DiagnosticSuggestion[] {
     return [{
       reason: 'Animations are still running when the command timed out',
       suggestions: [
@@ -174,7 +175,7 @@ export class TimeoutDiagnostics {
     }]
   }
 
-  private static analyzeDOMMutationIssues(context: TimeoutContext): DiagnosticSuggestion {
+  private static analyzeDOMMutationIssues (context: TimeoutContext): DiagnosticSuggestion {
     return {
       reason: `The DOM is changing rapidly (${context.domMutations} mutations detected)`,
       suggestions: [
@@ -187,20 +188,19 @@ export class TimeoutDiagnostics {
     }
   }
 
-  private static getGeneralSuggestions(context: TimeoutContext): DiagnosticSuggestion {
+  private static getGeneralSuggestions (context: TimeoutContext): DiagnosticSuggestion {
     const { command, timeout, selector } = context
+    const escapedSelector = selector ? this.escapeSelector(selector) : undefined
 
     const generalSuggestions = [
-      `Increase timeout if needed: cy.${command}(${selector ? `'${selector}', ` : ''}{ timeout: ${timeout * 2} })`,
+      `Increase timeout if needed: cy.${command}(${escapedSelector ? `'${escapedSelector}', ` : ''}{ timeout: ${timeout * 2} })`,
       'Verify the element/condition you\'re waiting for actually appears',
       'Check the browser console and Network tab for errors',
       'Use .debug() before the failing command to inspect the state: cy.debug()',
     ]
 
     // Add command-specific suggestions
-    if (['get', 'contains'].includes(command) && selector) {
-      const escapedSelector = selector.replace(/'/g, "\\'");
-
+    if (command === 'get' && escapedSelector) {
       generalSuggestions.unshift(
         `Verify selector in DevTools: document.querySelector('${escapedSelector}')`,
         'Ensure the element is not hidden by CSS (display: none, visibility: hidden)',
@@ -221,17 +221,23 @@ export class TimeoutDiagnostics {
     }
   }
 
+  private static escapeSelector (selector: string): string {
+    return selector
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, '\\\'')
+  }
+
   /**
    * Format diagnostic suggestions into a readable message
    */
-  static formatSuggestions(suggestions: DiagnosticSuggestion[]): string {
+  static formatSuggestions (suggestions: DiagnosticSuggestion[]): string {
     if (suggestions.length === 0) return ''
 
     let output = '\n\n🔍 Diagnostic Suggestions:\n'
 
     suggestions.forEach((suggestion, index) => {
       output += `\n${index + 1}. ${suggestion.reason}\n`
-      
+
       suggestion.suggestions.forEach((tip, tipIndex) => {
         output += `   ${String.fromCharCode(97 + tipIndex)}) ${tip}\n`
       })
@@ -247,10 +253,10 @@ export class TimeoutDiagnostics {
   /**
    * Enhanced error message with diagnostics
    */
-  static enhanceTimeoutError(originalMessage: string, context: TimeoutContext): string {
+  static enhanceTimeoutError (originalMessage: string, context: TimeoutContext): string {
     const suggestions = this.analyze(context)
     const diagnostics = this.formatSuggestions(suggestions)
-    
+
     return originalMessage + diagnostics
   }
 }

packages/driver/test/unit/cypress/timeout_diagnostics.spec.ts

@@ -23,14 +23,33 @@ describe('TimeoutDiagnostics', () => {
     it('escapes quotes in dynamic content selector suggestions', () => {
       const context = {
         command: 'get',
-        selector: "[data-test='loading']",
+        selector: '[data-test=\'loading\']',
         timeout: 4000,
       }
 
       const suggestions = TimeoutDiagnostics.analyze(context)
 
       expect(suggestions).toHaveLength(1)
-      expect(suggestions[0].suggestions.some((s) => s.includes("\\'"))).toBe(true)
+      expect(suggestions[0].suggestions.some((s) => s.includes('\\\''))).toBe(true)
+    })
+
+    it('preserves template literal characters in selector suggestions', () => {
+      const context = {
+        command: 'get',
+        selector: '[data-test=`value-${state}`]',
+        timeout: 4000,
+      }
+
+      const suggestions = TimeoutDiagnostics.analyze(context)
+      const combined = suggestions.reduce<string[]>((acc, suggestion) => {
+        acc.push(...suggestion.suggestions)
+
+        return acc
+      }, []).join('\n')
+
+      expect(combined).toContain('`value-${state}`')
+      expect(combined).not.toContain('\\`')
+      expect(combined).not.toContain('\\${')
     })
 
     it('detects complex selectors', () => {
@@ -55,6 +74,9 @@ describe('TimeoutDiagnostics', () => {
       const suggestions = TimeoutDiagnostics.analyze(context)
 
       expect(suggestions.some((s) => s.reason.includes('dynamically generated'))).toBe(true)
+      const dynamicIdSuggestion = suggestions.find((s) => s.reason.includes('dynamically generated'))
+
+      expect(dynamicIdSuggestion?.suggestions.some((tip) => tip.includes('[id^="user-"'))).toBe(true)
     })
 
     it('detects network issues with many pending requests', () => {
@@ -94,9 +116,9 @@ describe('TimeoutDiagnostics', () => {
       const suggestions = TimeoutDiagnostics.analyze(context)
 
       expect(suggestions.some((s) => s.reason.includes('Animations are still running'))).toBe(true)
-      expect(suggestions.some((s) => 
-        s.suggestions.some((sug) => sug.includes('waitForAnimations: false')),
-      )).toBe(true)
+      expect(suggestions.some((s) => {
+        return s.suggestions.some((sug) => sug.includes('waitForAnimations: false'))
+      })).toBe(true)
     })
 
     it('detects excessive DOM mutations', () => {
@@ -126,6 +148,21 @@ describe('TimeoutDiagnostics', () => {
       expect(suggestions[0].suggestions.length).toBeGreaterThan(0)
     })
 
+    it('avoids document.querySelector advice for contains text queries', () => {
+      const context = {
+        command: 'contains',
+        selector: 'Success',
+        timeout: 4000,
+      }
+
+      const suggestions = TimeoutDiagnostics.analyze(context)
+
+      expect(suggestions).toHaveLength(1)
+      const combinedSuggestions = suggestions[0].suggestions.join('\n')
+
+      expect(combinedSuggestions.includes('document.querySelector')).toBe(false)
+    })
+
     it('provides command-specific suggestions for click', () => {
       const context = {
         command: 'click',
@@ -135,9 +172,9 @@ describe('TimeoutDiagnostics', () => {
 
       const suggestions = TimeoutDiagnostics.analyze(context)
 
-      expect(suggestions[0].suggestions.some((s) => 
-        s.includes('visible, enabled, and not covered'),
-      )).toBe(true)
+      expect(suggestions[0].suggestions.some((s) => {
+        return s.includes('visible, enabled, and not covered')
+      })).toBe(true)
     })
   })
 
@@ -242,15 +279,15 @@ describe('TimeoutDiagnostics', () => {
     it('escapes quotes in code suggestions to prevent syntax errors', () => {
       const context = {
         command: 'get',
-        selector: "[data-test='value']",
+        selector: '[data-test=\'value\']',
         timeout: 4000,
       }
 
       const suggestions = TimeoutDiagnostics.analyze(context)
       const formatted = TimeoutDiagnostics.formatSuggestions(suggestions)
 
       // Verify quotes are escaped in suggestions
-      expect(formatted.includes("\\'")).toBe(true)
+      expect(formatted.includes('\\\'')).toBe(true)
       // Verify no unescaped single quotes that would break JS
       expect(formatted.match(/cy\.get\('\[data-test='value'\]'\)/)).toBe(null)
     })