Troubleshooting Selectors

This guide helps you identify and fix common selector issues in TrueAssert tests.

Overview

Selector issues are a common cause of test failures. This guide covers:

• How to identify selector problems

• Common selector issues and fixes

• Step-by-step debugging process

• Tools and techniques for fixing selectors

Identifying Selector Issues

Symptoms

Test Fails with:

• "Element not found" error

• "Selector not unique" error

• "Timeout waiting for element" error

• Intermittent failures

Visual Indicators:

• Screenshot shows element doesn't exist

• Screenshot shows element in different location

• Screenshot shows page structure changed

Common Selector Problems

Problem 1: Selector Not Found

Error: Element not found: //button[@id='submit']

Possible Causes:

1. Element doesn't exist on page

2. Element hasn't loaded yet

3. Selector is incorrect

4. Page structure changed

Debugging Steps:

1. Check Screenshot: See what page actually looks like

2. Inspect in Browser: Open page in browser DevTools

3. Test Selector: Try selector in browser console:

   $x("//button[@id='submit']")

4. Check Timing: Add WAIT step if element loads slowly

Solutions:

• Fix Selector: Update to correct selector

• Add WAIT: Wait for element to appear

• Check Page: Verify page structure hasn't changed

Problem 2: Selector Not Unique

Error: Selector matches multiple elements

Possible Causes:

1. Multiple elements match selector

2. Selector too generic

3. Missing positional index

Debugging Steps:

1. Test in Console: See how many elements match:

   $x("//button[@class='submit']").length

2. Check Screenshot: See all matching elements

3. Review Selector: Identify why it's not unique

Solutions:

• Add Positional Index: (//button[@class='submit'])[1]

• Use More Specific Selector: Add more attributes

• Use Parent Anchor: //div[@id='form']//button[@class='submit']

Problem 3: Selector Too Brittle

Error: Test works sometimes but fails other times

Possible Causes:

1. Using CSS classes that change

2. Using structural positioning

3. Using dynamic attributes

Debugging Steps:

1. Review Selector: Check what type of selector it is

2. Check Quality: See selector penalty/quality

3. Test Multiple Times: Run test multiple times to confirm

Solutions:

• Update to Stable Selector: Use ID or data-testid

• Use Better Attributes: Prefer semantic attributes

• Add Parent Anchor: Use stable parent

Problem 4: Timing Issues

Error: Element not found (but exists on page)

Possible Causes:

1. Element loads after page load

2. Element appears after animation

3. Element conditionally rendered

Debugging Steps:

1. Check Screenshot: See if element appears later

2. Review Page Load: Check if element is lazy-loaded

3. Test Timing: Add delays and see if it helps

Solutions:

• Add WAIT Step: Wait for element before interaction

• Wait for Condition: Wait for specific state

• Increase Timeout: If element takes longer

Debugging Process

Step 1: Understand the Error

1. Read error message carefully

2. Identify which step failed

3. Note the selector that failed

4. Check error details

Step 2: Visual Inspection

1. View screenshot at failure point

2. Compare with expected state

3. Look for missing elements

4. Check for structural changes

Step 3: Test Selector Manually

1. Open page in browser

2. Open DevTools console

3. Test selector:

   // For XPath
   $x("//button[@id='submit']")
   
   // For CSS
   document.querySelector("#submit")

4. Verify selector matches element

Step 4: Analyze the Issue

1. Does Element Exist?: Check if element is on page

2. Is Selector Correct?: Verify selector syntax

3. Is Timing Issue?: Check if element loads later

4. Has Page Changed?: Compare with previous version

Step 5: Fix the Selector

1. Update Selector: Fix incorrect selector

2. Use Better Attributes: Switch to ID or data-testid

3. Add WAIT: Add wait if timing issue

4. Use Alternative: Try alternative selector

Step 6: Verify the Fix

1. Save updated selector

2. Run test again

3. Verify it works

4. Monitor for future issues

Tools and Techniques

Browser DevTools

Inspect Element:

1. Right-click element

2. Select "Inspect"

3. See element in DOM

4. Check attributes available

Test XPath:

// In browser console
$x("//button[@id='submit']")

Test CSS:

// In browser console
document.querySelector("#submit")

TrueAssert Features

Alternative Selectors:

• View alternative selectors if available

• Try different selector options

• Save alternatives to repository

Selector Repository:

• Save good selectors for reuse

• Share selectors across tests

• Maintain selector library

Specific Fixes

Fix 1: Update to ID Selector

Before:

//button[contains(@class, 'submit-btn')]

After:

//button[@id='submit']

Why: ID is more stable than class

Fix 2: Add Parent Anchor

Before:

//button[@type='submit']

After:

//form[@id='login-form']//button[@type='submit']

Why: Parent provides context and stability

Fix 3: Add Positional Index

Before:

//div[@class='item']

After:

(//div[@class='item'])[2]

Why: Makes selector unique when multiple match

Fix 4: Add WAIT Step

Before:

CLICK //button[@id='submit']

After:

WAIT //button[@id='submit']
CLICK //button[@id='submit']

Why: Ensures element is loaded before interaction

Fix 5: Use data-testid

Before:

//div[contains(@class, 'user-menu')]

After:

//div[@data-testid='user-menu']

Why: data-testid is explicit test contract

Prevention

During Test Creation

1. Use Recording: Recording generates better selectors

2. Review Selectors: Check generated selectors

3. Test Immediately: Run test to verify selectors work

4. Fix Early: Update selectors before they break

During Development

1. Add IDs: Give important elements stable IDs

2. Use data-testid: Add test IDs for test elements

3. Avoid Dynamic Classes: Don't use random class names

4. Stable Structure: Keep DOM structure relatively stable

Regular Maintenance

1. Monitor Failures: Track selector-related failures

2. Update Proactively: Fix selectors before they break

3. Document Changes: Note page structure changes

4. Test Regularly: Run tests frequently to catch issues

Advanced Debugging

Selector Validation

Test selector in browser console:

// XPath
const elements = $x("//button[@id='submit']");
console.log("Found", elements.length, "elements");

// CSS
const element = document.querySelector("#submit");
console.log("Element:", element);

Multiple Selectors

Try different selector options:

// Option 1: ID
$x("//button[@id='submit']")

// Option 2: data-testid
$x("//button[@data-testid='submit']")

// Option 3: ARIA
$x("//button[@aria-label='Submit']")

Selector Alternatives

If primary selector fails:

1. Check if alternative selectors exist

2. Try alternative selector

3. Update test to use alternative

4. Save alternative to repository

Related Topics

• Understanding XPath Selectors - How selectors work

• Selector Best Practices - Create good selectors

• Debugging Failed Tests - General debugging

• Browser Plugin Recording - Generate selectors

---

← Back to Documentation | Next: Tutorials →