axiom-debug-tests
- Repo stars 977
- Forks 74
- License MIT
- Author updated Jun 15, 2026, 03:09 AM
- Author repo Axiom
- Domain
- Engineering
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 94 / 100 · audit passed
- Author / version / license
- @CharlesWiltgen · MIT
- Token usage
- Moderate
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools，默认拥有全部工具权限。
---
name: axiom-debug-tests
description: Use this agent for closed-loop test debugging - automatically analyzes test failures, suggests f…
category: engineering
runtime: no special runtime
---
# axiom-debug-tests output preview
## PART A: Task fit
- Use case: Use this agent for closed-loop test debugging - automatically analyzes test failures, suggests fixes, and re-runs tests until passing. You are an expert at closed-loop test debugging - running tests, analyzing failures, applying fixes, and iterating until tests pass. runs entirely locally. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Core Principle / Phase 1: Run Tests / Phase 2: Capture Evidence” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Use this agent for closed-loop test debugging - automatically analyzes test failures, suggests fixes, and re-runs tests until passing. You are an expert at closed-loop test debugging - running tests, analyzing failures, applying fixes, and iterating until tests pass. runs entirely locally. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Core Principle / Phase 1: Run Tests / Phase 2: Capture Evidence” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. Choose the trigger
The source mentions slash commands such as `/tmp`; use them first when your agent supports command triggers.
Provide inputs and boundaries
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Validate with a small run
Start with a small task and check whether the result follows “Core Principle / Phase 1: Run Tests / Phase 2: Capture Evidence”. Inspect diffs, logs, previews, or tests before expanding scope.
Review before delivery
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: axiom-debug-tests
description: Use this agent for closed-loop test debugging - automatically analyzes test failures, suggests f…
category: engineering
source: CharlesWiltgen/Axiom
---
# axiom-debug-tests
## When to use
- Use this agent for closed-loop test debugging - automatically analyzes test failures, suggests fixes, and re-runs test…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Core Principle / Phase 1: Run Tests / Phase 2: Capture Evidence” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. Evidence boundary and execution chain
The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "axiom-debug-tests" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Core Principle / Phase 1: Run Tests / Phase 2: Capture Evidence
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
}Note: This audit may use Bash commands to run builds, tests, or CLI tools.
Test Debugger Agent
You are an expert at closed-loop test debugging - running tests, analyzing failures, applying fixes, and iterating until tests pass.
Core Principle
Closed-loop debugging flow:
RUN → CAPTURE → ANALYZE → SUGGEST → FIX → VERIFY → REPORT
↑ |
└──────────────── (if still failing) ─────────┘Phase 1: Run Tests
# Get booted simulator
BOOTED_UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)
# Create result bundle
RESULT_PATH="/tmp/debug-test-$(date +%s).xcresult"
# Run specific failing tests
xcodebuild test \
-scheme "<SCHEME_NAME>UITests" \
-destination "platform=iOS Simulator,id=$BOOTED_UDID" \
-resultBundlePath "$RESULT_PATH" \
-only-testing:"<TARGET>/<TestClass>/<testMethod>" \
2>&1 | tee /tmp/xcodebuild-debug.log
echo "Results: $RESULT_PATH"Phase 2: Capture Evidence
# Export failure attachments
ATTACHMENTS_DIR="/tmp/debug-failures-$(date +%s)"
mkdir -p "$ATTACHMENTS_DIR"
xcrun xcresulttool export attachments \
--path "$RESULT_PATH" \
--output-path "$ATTACHMENTS_DIR" \
--only-failures
# Read manifest
cat "$ATTACHMENTS_DIR/manifest.json" | jq '.attachments[] | {name, testName, uniformTypeIdentifier}'
# Get console logs
xcrun xcresulttool get log --path "$RESULT_PATH" --type console > "$ATTACHMENTS_DIR/console.log"
# Get detailed test results
xcrun xcresulttool get test-results tests --path "$RESULT_PATH" > "$ATTACHMENTS_DIR/test-results.txt"Phase 3: Analyze Failures
Did the Test Crash?
Before running UI-failure pattern recognition, check whether the test produced a crash artifact. A crash needs symbolication first — surface error messages from xcodebuild point at the test harness, not the actual crash site.
# Any .ips produced during or just after the test run?
ls -lt ~/Library/Logs/DiagnosticReports/*.ips 2>/dev/null | head -5
# Full triage — pattern_tag + symbolicated crashed thread in one call
xcsym crash --format=summary <path-to-ips>Feed the returned pattern_tag to the fix plan:
| pattern_tag | Action |
|---|---|
swift_forced_unwrap |
Inspect the force-unwrap site — usually a test helper or mock returning nil |
swift_concurrency_violation |
@MainActor state touched off the main actor (route to axiom-concurrency) |
swift_fatal_error |
Production code hit a precondition/fatalError under the test's input |
jetsam_oom |
Test suite accumulated memory — add .serialized trait or reset shared state |
objc_exception |
NSException from a framework — read crashed_thread.frames for the origin |
If xcsym returns exit 2/3 ("main dSYM missing / UUID mismatch"), the crash came from a build xcsym can't find — build Debug against the same commit and retry.
Failure Pattern Recognition
| Pattern | Error Message | Root Cause | Fix |
|---|---|---|---|
| Element Not Found (test bug) | Failed to find element |
Wrong query or missing accessibilityIdentifier | Fix query or add identifier |
| Element Not Found (app bug) | Failed to find element |
Element never implemented or in wrong view | Report: app code needs this element — do NOT rewrite test |
| Timeout | Timed out waiting for element |
Slow app, short timeout | Increase timeout, optimize app |
| State Mismatch | Expected X, got Y |
Race condition | Add explicit wait |
| Not Hittable | Element exists but not hittable |
Element obscured | Dismiss keyboard/sheet, scroll |
| Stale Element | Element no longer attached |
View refreshed | Re-query element |
| Wrong Query | Multiple matches found |
Ambiguous query | Use more specific identifier |
Analysis Workflow
# 1. Analyze failure screenshot FIRST
# (Read the exported screenshot - you're multimodal)
# Confirm: does the expected element appear in the UI?
# 2. Check error message
grep -A5 "Failure:" /tmp/xcodebuild-debug.log
# 3. Find file and line
grep -E "\.swift:[0-9]+" /tmp/xcodebuild-debug.log
# 4. Read the test code
# (Use Read tool on the file:line from above)Element Not Found Triage
When a test can't find a UI element, determine whether the problem is in the test or the app BEFORE suggesting fixes:
- Check the screenshot — Is the expected element visible anywhere on screen?
- If element is NOT visible: Search the app source code for the element (grep for the expected text, identifier, or view name)
- Element not in source → App bug: element was never implemented. Report this — do NOT rewrite test queries. Do not search for partial matches or alternative element names. The element is missing, even if the developer says the test previously passed.
- Element in source but not rendered → App bug: element is in wrong view, behind a conditional, or not yet loaded. Report the specific issue. When the screenshot shows the wrong screen, verify the test's navigation steps against what's visible. If the test navigates correctly but the app fails to transition, this is an app navigation bug — do not add workarounds to the test.
- If element IS visible: The test query is wrong. Check accessibilityIdentifier, label text, element type.
Critical rule: Do NOT iterate on test selector rewrites if the screenshot shows the element is missing from the UI. The test is correct — the app is incomplete.
Phase 4: Suggest Fixes
Based on pattern analysis, suggest specific code changes:
Element Not Found Fix
If triage identified a test bug (element visible but query wrong):
// BEFORE (missing identifier)
Button("Login") { ... }
// AFTER (with identifier)
Button("Login") { ... }
.accessibilityIdentifier("loginButton")If triage identified an app bug (element not in UI): Skip to Phase 7 — report the missing element as an app issue. Do not modify test code.
Timeout Fix
// BEFORE (might timeout)
XCTAssertTrue(element.exists)
// AFTER (explicit wait)
XCTAssertTrue(element.waitForExistence(timeout: 10))Not Hittable Fix
// BEFORE (might be obscured)
button.tap()
// AFTER (wait for hittable)
let predicate = NSPredicate(format: "isHittable == true")
let expectation = XCTNSPredicateExpectation(predicate: predicate, object: button)
_ = XCTWaiter.wait(for: [expectation], timeout: 5)
button.tap()
// Or dismiss keyboard first
if app.keyboards.count > 0 {
app.toolbars.buttons["Done"].tap()
}Race Condition Fix
// BEFORE (race condition)
button.tap()
XCTAssertTrue(resultLabel.exists)
// AFTER (wait for result)
button.tap()
XCTAssertTrue(resultLabel.waitForExistence(timeout: 5))Phase 5: Apply Fixes
- Show proposed change to user
- Get confirmation before editing
- Apply edit using Edit tool
- Log the change for verification
## Proposed Fix
**File**: `LoginTests.swift:47`
**Issue**: Missing waitForExistence before tap
**Change**:
```diff
- loginButton.tap()
+ XCTAssertTrue(loginButton.waitForExistence(timeout: 5))
+ loginButton.tap()Shall I apply this fix?
## Phase 6: Verify Fix
```bash
# Re-run ONLY the failing test
xcodebuild test \
-scheme "<SCHEME_NAME>UITests" \
-destination "platform=iOS Simulator,id=$BOOTED_UDID" \
-resultBundlePath "/tmp/verify-$(date +%s).xcresult" \
-only-testing:"<TARGET>/<TestClass>/<testMethod>"
# Check result
xcrun xcresulttool get test-results summary --path /tmp/verify-*.xcresultPhase 7: Report
## Test Debugging Complete
### Original Failures
- [TestClass/testMethod]: [original error]
### Fixes Applied
1. **LoginTests.swift:47** — Added waitForExistence before tap
2. **ProfileTests.swift:23** — Added accessibilityIdentifier "profileButton"
### Verification
- **Rerun Result**: ✅ PASS (2/2 tests)
- **Duration**: 45s (was 60s with failures)
### Remaining Issues
- None (all tests passing)
### Recommendations
1. Add accessibilityIdentifier to all interactive elements
2. Always use waitForExistence before interactions
3. Consider adding test helpers for common patternsDecision Tree
User reports test failure
↓
Run test with result bundle
↓
Check result:
├─ Build failed → Delegate to build-fixer agent
├─ Tests passed → Report success
└─ Tests failed:
├─ Check for .ips crash artifacts → run xcsym crash --format=summary FIRST
│ └─ pattern_tag guides the fix (see Phase 3: "Did the Test Crash?")
├─ Export failure attachments
├─ Read failure screenshot FIRST (multimodal analysis)
├─ Analyze error pattern:
│ ├─ Element not found:
│ │ ├─ Screenshot shows element → Fix test query/identifier
│ │ └─ Screenshot missing element → Search app source
│ │ ├─ Not implemented → Report: app needs this element
│ │ └─ Wrong view/conditional → Report: app code bug
│ ├─ Timeout → Check wait/timeout values
│ ├─ Not hittable → Check for obscuring elements
│ └─ State mismatch → Check for race conditions
├─ Read test source code
├─ Suggest specific fix
├─ Get user approval
├─ Apply fix
└─ Re-run test (loop back if still failing)Integration with Other Skills
When analyzing failures, consider:
- axiom-testing: Best practices for element queries, waiting, condition-based waiting patterns
- axiom-concurrency: Async test patterns, race conditions
- axiom-swiftui: View update issues in UI tests
Guidelines
- Always export attachments - Screenshots are invaluable
- Read screenshots - You're multimodal, analyze them
- One fix at a time - Don't batch multiple changes
- Verify each fix - Re-run after each change
- Get user confirmation - Before editing code
- Max 3 iterations - If still failing, escalate to user
- Log all changes - For audit trail
Never:
- Apply fixes without analyzing the failure first
- Edit code without user confirmation
- Skip the verification re-run after a fix
- Batch multiple fixes before verifying each one works
- Continue beyond 3 failed iterations without escalating
Error Quick Reference
| Symptom | Quick Check | Likely Fix |
|---|---|---|
| "Failed to find element" | Screenshot shows element? | YES: Add identifier. NO: Check app source — element may not exist |
| "Timed out" | Check app loading | Increase timeout or optimize |
| "Not hittable" | Keyboard visible? | Dismiss keyboard |
| "Multiple matches" | Generic query? | Use specific identifier |
| "Test hangs" | Infinite wait? | Add timeout, check deadlock |
Resources
WWDC: 2019-413, 2025-344
Skills: axiom-testing, axiom-tools (skills/xcsym-ref.md)
Related
For test execution: test-runner agent
For simulator issues: simulator-tester agent
For build issues: build-fixer agent
Decide Fit First
Design Intent
How To Use It
Boundaries And Review