# Test Debugger Skill

A specialized Claude Code skill for debugging Playwright test failures in the Halo QA Automation project.

## What It Does

The test-debugger skill helps you quickly diagnose and fix test failures by:
- Analyzing test results and error traces
- Identifying root causes of failures
- Providing specific code fixes with line numbers
- Recommending better selectors from reference files
- Validating against project best practices

## When to Use

Invoke this skill whenever:
- A Playwright test fails and you need to debug it
- You need to understand why a test is timing out
- Selectors are not working as expected
- You want to validate test patterns against reference files
- You need quick suggestions to fix a failing test

## How to Invoke

Simply type the skill name in Claude Code:

```
test-debugger
```

Then provide context about the failure, such as:
- "Debug the latest test failure"
- "My dashboard export test is failing with a timeout"
- "The login test can't find the submit button"
- "Test failing at line 45 in dashboard-landing.spec.ts"

## What the Skill Analyzes

1. **Test Results**: Reads `test-results/results.json` and `junit.xml`
2. **Error Messages**: Extracts and interprets error details
3. **Test Files**: Reads the actual failing test code
4. **Page Objects**: Checks related page object implementations
5. **Reference Files**: Compares with working test patterns
6. **Selectors**: Validates against proven selector patterns

## Example Usage

### Example 1: Simple Failure
```
User: test-debugger
Claude: I'll help debug your test. What's the issue?
User: dashboard-export test is failing
Claude: [Analyzes results.json, finds timeout on Share button, suggests fix]
```

### Example 2: Specific Error
```
User: test-debugger
Claude: I'll help debug your test. What's the issue?
User: Getting "Element not found" error in add-all-smart-da-cards.spec.ts at line 52
Claude: [Reads the test file, compares with reference, identifies selector issue, provides exact fix]
```

## What You'll Get

The skill provides:
- **Problem Statement**: Clear description of what failed
- **Root Cause**: Why the failure occurred
- **Exact Fix**: File path, line number, before/after code
- **Explanation**: Why the fix works
- **Best Practices**: How to prevent similar issues

## Allowed Tools

The skill has access to:
- **Read**: Read test files, page objects, results
- **Glob**: Find files matching patterns
- **Grep**: Search for selectors, patterns, errors
- **Bash**: Execute commands to check test state
- **Edit**: Suggest specific edits to fix issues

## Common Issues It Fixes

1. **Selector Problems**: Wrong selectors, multiple matches, timing issues
2. **Login Failures**: Credential issues, page not loaded
3. **Widget Issues**: Widget not found, tab selection errors
4. **Timeout Errors**: Elements not appearing, slow loads
5. **Assertion Failures**: Expected vs actual mismatches
6. **Import Errors**: Wrong import paths for subfolder tests

## Reference Files It Uses

The skill knows about these proven working patterns:
- `tests/add-all-first-touch-attribution-cards.spec.ts`
- `tests/add-all-toured-conversions-cards.spec.ts`
- `tests/dashboard-export.spec.ts`
- All page objects in `/pages` directory
- Project patterns from `CLAUDE.md`

## Project Rules It Enforces

- Timeout must be `10 * 60 * 1000`
- Never use `waitForLoadState('networkidle')`
- Always use Page Object Model
- Credentials from process.env
- Correct import paths for subfolders
- Case-sensitive widget names

## Tips for Best Results

1. **Be Specific**: Mention the test name or file if known
2. **Provide Context**: Share error messages if you have them
3. **Recent Failures**: The skill automatically checks latest results
4. **Multiple Issues**: You can ask about multiple failures in sequence

## Integration with Project

This skill is aware of:
- Your CLAUDE.md project guidelines
- The 7-stage test automation pipeline
- Existing page object patterns
- Reference test implementations
- Project-specific selectors and workflows

## Next Steps After Debugging

Once you get a fix:
1. Apply the suggested changes
2. Run the test again: `npx playwright test [test-file] --headed --project=chromium`
3. If still failing, invoke the skill again for deeper analysis
4. Consider updating page objects if the issue is common

## Benefits

- **Faster debugging** - Get fixes in seconds instead of minutes
- **Learn patterns** - See how to write better tests
- **Consistency** - Follows project standards automatically
- **Comprehensive** - Checks multiple sources for root cause
- **Actionable** - Provides exact code to fix the issue

---

**Created**: 2025-10-23
**Version**: 1.0
**Maintained by**: QA Automation Team