Troubleshooting

Solutions to common problems in QAID.

Page Discovery Issues

Pages Not Being Discovered

Symptoms:

• Fewer pages found than expected
• Known pages missing from list

Possible Causes & Solutions:

Diagnostic Steps:

1. Check the discovery job status for errors
2. Review Max Pages and Max Depth settings
3. Manually verify pages are accessible
4. Check if authentication is needed

Too Many Irrelevant Pages

Symptoms:

• Admin pages discovered
• Utility pages cluttering list

Solutions:

1. Blacklist irrelevant pages after discovery
2. Add common patterns to blacklist:
   • /admin/*
   • /logout
   • /wp-admin/*
3. Reduce Max Depth to avoid deep navigation

Pages Showing as "Removed"

Symptoms:

• Previously discovered pages now show "removed" status

Causes:

• Page URL changed
• Page deleted from site
• Page now requires authentication
• Network issue during last crawl

Solutions:

1. Re-run discovery to check current state
2. Verify page exists manually
3. Check authentication settings

---

Element Extraction Issues

Elements Not Detected

Symptoms:

• Interactive elements missing
• Lower element count than expected

Possible Causes & Solutions:

Diagnostic Steps:

1. Manually inspect the page for the element
2. Check if element is in an iframe
3. Use browser DevTools to verify element exists
4. Check extraction job logs for errors

Wrong Selectors Generated

Symptoms:

• Tests fail with "element not found"
• Multiple elements match selector

Causes:

• Non-unique attributes
• Generic class names
• Dynamic IDs

Solutions:

1. Add data-testid attributes to key elements
2. Use more specific HTML structure
3. Re-run extraction after site changes

Quality Issues Tab Shows Many Problems

This is informational. Quality issues help you improve your site:

1. Review each issue type
2. Prioritize accessibility issues
3. Fix underlying problems in your application
4. Re-run extraction to verify fixes

---

Test Generation Issues

Low Coverage Score

Symptoms:

• Coverage below 50%
• Many elements without tests

Solutions:

1. Add data-testid attributes to important elements
2. Use scenario tests to cover interactive flows (modals, dropdowns, multi-step forms)
3. Review uncovered elements and accept ones that aren't worth testing

Tests Failing After Generation

Symptoms:

• Newly generated tests fail immediately

Possible Causes:

• Site changed during generation
• Timing issues
• Authentication problems

Solutions:

1. Verify site is stable
2. Re-run element extraction
3. Regenerate tests
4. Check authentication settings
5. Increase timeouts if timing-related

Scenario Generation Fails

Symptoms:

• "Generate Test" button errors
• Scenario shows no test code

Causes:

• Elements not found in database
• Page structure changed
• AI couldn't plan valid actions

Solutions:

1. Re-run element extraction
2. Simplify scenario description
3. Check that referenced page has elements
4. Review mapped elements for issues

---

Test Execution Issues

Tests Fail Intermittently

Symptoms:

• Same test passes sometimes, fails other times

Possible Causes:

Tests Fail with "Element Not Found"

Symptoms:

• TimeoutError: locator.click: Target closed
• Element locator returns null

Diagnostic Steps:

1. Check if element still exists on page
2. Verify selector in browser DevTools
3. Check if page loaded correctly
4. Verify authentication worked

Solutions:

1. Re-extract elements
2. Regenerate the failing test
3. Check for site changes
4. Verify credentials

Tests Fail with "Strict Mode Violation"

Symptoms:

• Error mentions "resolved to multiple elements"

Cause:

• Selector matches more than one element

Solutions:

1. Test needs more specific selector
2. Add .first() to selector
3. Add unique identifiers to elements
4. Regenerate test after re-extraction

---

Visual Regression Issues

Too Many False Positives

Symptoms:

• Tests fail but page looks correct
• Dynamic content flagged as changes

Solutions:

1. Increase threshold percentage (2-5%)
2. Increase wait time for animations
3. Use Record & Snap for consistent states
4. Review AI analysis results

Baseline Not Capturing Correctly

Symptoms:

• Screenshot is blank or partial
• Wrong page captured

Possible Causes:

Record & Snap Not Working

Prerequisites Checklist:

• Chrome Extension installed
• Extension ID configured in QAID
• Extension enabled on target site
• Browser not blocking extension

If still not working:

1. Reinstall extension
2. Re-copy Extension ID
3. Clear browser cache
4. Try in new Chrome profile

---

Extension Issues

Extension Not Connecting

Symptoms:

• QAID can't communicate with extension
• Record features don't work

Diagnostic Steps:

1. Verify Extension ID in settings
2. Check extension is enabled in Chrome
3. Open chrome://extensions and verify status

Solutions:

1. Re-copy Extension ID exactly
2. Enable extension
3. Grant site permissions
4. Restart Chrome

Recording Actions Not Captured

Symptoms:

• Actions performed but not in timeline

Possible Causes:

• Recording not started
• Element in iframe
• Shadow DOM element
• Permission denied

Solutions:

1. Ensure "Start Recording" was clicked
2. Check element is accessible
3. Grant extension permissions
4. Try different interaction method

---

Performance Issues

QAID is Slow

Possible Causes & Solutions:

Jobs Taking Too Long

Symptoms:

• Jobs run for many minutes
• Progress seems stuck

Solutions:

1. Check job logs for errors
2. Reduce scope (fewer pages)
3. Verify site is responding
4. Cancel and retry
5. Check system resources

High AI Costs

Review usage:

1. Check Admin > API Usage (Enterprise) for cost breakdown
2. Identify expensive operations
3. Enable Production-Safe Mode
4. Reduce page count
5. Run fewer concurrent test executions

---

Authentication Issues

Crawler Can't Access Protected Pages

Symptoms:

• Protected pages show as empty
• Login page keeps appearing

Diagnostic Steps:

1. Verify credentials work manually
2. Check authentication type is correct
3. Look for CAPTCHA or 2FA
4. Check for session expiry

Solutions:

1. Update credentials
2. Try Basic Auth if supported
3. Check for account lockout
4. Verify login page URL

Tests Fail After Login Changes

Symptoms:

• Tests that worked now fail
• Authentication errors in logs

Solutions:

1. Update stored credentials
2. Re-run element extraction
3. Regenerate auth-dependent tests
4. Check for password expiry

---

Getting More Help

Check Logs

• Job logs show detailed progress
• Browser console for frontend issues
• Server logs for backend errors

Retry Operations

Many issues resolve with retry:

1. Cancel current operation
2. Wait a moment
3. Try again

Reset and Rebuild

For persistent issues:

1. Delete the project and create a new one
2. Start fresh with discovery
3. Rebuild element database
4. Regenerate tests

Community Support

• Check documentation
• Search FAQ
• Report issues with reproduction steps

---

Related Topics

• FAQ - Common questions
• Settings - Configuration options
• Glossary - Term definitions