Debugging Tests

When tests fail, AegisRunner provides multiple tools and techniques to help you identify and fix issues quickly. This guide covers how to effectively debug failing tests.

Understanding Test Failures

Tests can fail for various reasons:

Failure Type	Common Causes
Element Not Found	Selector changed, element removed, timing issue
Timeout	Page slow to load, element never appears
Assertion Failed	Expected value doesn't match actual
Navigation Error	Page not found, redirect issue
JavaScript Error	Runtime error in your application

Viewing Failure Details

Debugging Tools

Screenshots

AegisRunner captures screenshots at the point of failure:

• Shows exact page state when the test failed
• Helps identify visual issues
• Useful for catching unexpected modals or overlays

Trace Files Pro+

Pro and Business plans include Playwright trace files with:

• Timeline - Step-by-step execution timeline
• Screenshots - Screenshot at each action
• Network - All HTTP requests and responses
• Console - Browser console logs
• DOM Snapshots - HTML state at each step

Download the trace and open it in the Playwright Trace Viewer:

npx playwright show-trace trace.zip

HAR Files Pro+

When HAR recording is enabled, analyze network activity:

• Failed API requests
• Slow responses
• Missing resources
• CORS issues

Common Issues and Solutions

Element Not Found

Symptoms: "Cannot find element matching selector..."

Solutions:

• Check if the selector is still valid in your app
• Use more stable selectors (data-testid, IDs) instead of classes
• Add a wait condition before interacting with the element
• Check if the element is inside an iframe
• Verify the page navigation completed before looking for the element

Timeout Errors

Symptoms: "Timeout exceeded while waiting..."

Solutions:

• Increase timeout values for slow operations
• Check network conditions during the test
• Verify the action completes in manual testing
• Look for loading spinners or async operations
• Add explicit wait conditions for async content

Assertion Failures

Symptoms: "Expected X but received Y"

Solutions:

• Verify the expected value is still correct
• Check for data changes in your application
• Use flexible matchers for dynamic content
• Update test data if business logic changed

Flaky Tests

Symptoms: Test passes sometimes, fails other times

Solutions:

• Add proper wait conditions
• Avoid race conditions in assertions
• Use stable, deterministic test data
• Check for time-dependent logic
• Ensure test isolation (no shared state)

Authentication Issues

Symptoms: Test redirects to login, unauthorized errors

Solutions:

• Configure pre-authentication cookies in Test Data
• Set up environment tokens for API authentication
• Create a login user flow that runs first
• Check if session expired

Using Test Data for Debugging

Configure debugging aids in Test Data:

Environment Tokens

Set API keys or bypass tokens that help tests authenticate or skip certain checks.

Pre-Authentication Cookies

Inject session cookies to bypass login flows during testing.

Custom HTTP Headers

Add headers for debugging (e.g., X-Debug-Mode: true).

Best Practices

Running Tests Locally

For deep debugging, export and run tests locally:

1. Click Export Playwright on the failing suite
2. Download the .spec.ts file
3. Install Playwright: npm init playwright@latest
4. Run with debug mode: npx playwright test --debug
5. Step through the test interactively

# Run with headed browser (visible)
npx playwright test --headed

# Run with debug mode (step through)
npx playwright test --debug

# Run specific test file
npx playwright test my-test.spec.ts

Reporting Issues

If you believe a test failure is due to an AegisRunner bug:

1. Export the failing test
2. Download trace files if available
3. Note the test run ID
4. Contact support with details

Related Documentation

• Running Tests - Execute and view test runs
• Test Data Management - Configure test environment
• Common Issues - General troubleshooting