docs(skill): document AXe vs XCUITest event model differences

[gwillish]

I've been using Axe with the skill over the last couple of weekends, did some retrospectives on the transcripts, and identified this update that I think is worth adding to the skill, at least where it comes to using it when debugging and setting up XCUITest cases.

AXe sends pure HID touch events; XCUITest element.tap() sends UIAccessibilityActivate (an AX action). These are not equivalent, which causes confusing failures when using both tools together:

• An AX-action bug (e.g. iOS 26 @observable sheet dismissal) looks fine under AXe but fails under XCUITest — AXe cannot reproduce it.
• A HID tap inside a UIScrollView (List/Form) fails under AXe but succeeds under XCUITest because AX actions bypass the scroll gesture recognizer.

Adds a "different event models" callout to Step 3 so users know which tool is authoritative for which failure mode.

What do you think? Okay - or blurring the lines for the skill since there's overlap with other technology there?

[coderabbitai]

Walkthrough

A new section titled "AXe vs XCUITest — different event models" was added to the documentation. This section explains the differences between AXe HID touch commands and XCUITest's accessibility action (UIAccessibilityActivate), noting these event paths are not equivalent. The documentation outlines two contrasting failure scenarios: bugs reproducible only through XCUITest's accessibility action may not appear with AXe, and conversely, AXe HID taps can be intercepted by scroll gestures whilst XCUITest's accessibility action bypasses them. Guidance is provided for diagnostic troubleshooting using app.debugDescription within XCUITest.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: documenting differences between AXe and XCUITest event models in the skill documentation.
Description check	✅ Passed	The description is directly related to the changeset, providing clear context about AXe HID touch events versus XCUITest accessibility actions and explaining the practical failure modes that motivated the documentation update.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

Skills/CLI/axe/SKILL.md (1)

33-39: Excellent addition — provides critical context for troubleshooting.

This new section clearly explains the fundamental difference between AXe's HID touch events and XCUITest's accessibility actions, along with concrete failure scenarios. The guidance to use app.debugDescription when XCUITest fails is particularly valuable.

The content is technically accurate and well-positioned within Step 3's execution model discussion.

Optional: Minor readability improvements

Static analysis suggests adding commas to improve flow:

-AXe sends pure HID touch events. XCUITest's `element.tap()` sends `UIAccessibilityActivate` (an AX action), which bypasses the touch system entirely. These are not equivalent:
-- A bug that only manifests under XCUITest's AX action (e.g. a SwiftUI sheet dismissing when an `@Observable` store mutates during an AX action) **cannot be reproduced or diagnosed with AXe**. AXe will show correct behavior while XCUITest fails.
+AXe sends pure HID touch events. XCUITest's `element.tap()` sends `UIAccessibilityActivate` (an AX action), which bypasses the touch system entirely. These are not equivalent:
+- A bug that only manifests under XCUITest's AX action (e.g. a SwiftUI sheet dismissing when an `@Observable` store mutates during an AX action) **cannot be reproduced or diagnosed with AXe**. AXe will show correct behavior, whilst XCUITest fails.
 - Conversely, AXe HID taps can be intercepted by a scroll gesture recognizer inside a `UIScrollView` (SwiftUI `List`/`Form`), while XCUITest's AX action bypasses the gesture system entirely.
 
-When AXe shows "it works" but XCUITest fails: the bug is in the AX action interaction, not the app's visual behavior. Switch to `app.debugDescription` inside a diagnostic XCUITest for ground truth — AXe `describe-ui` cannot capture in-process XCUITest state.
+When AXe shows "it works" but XCUITest fails, the bug is in the AX action interaction, not the app's visual behavior. Switch to `app.debugDescription` inside a diagnostic XCUITest for ground truth — AXe `describe-ui` cannot capture in-process XCUITest state.

These are purely stylistic and entirely optional.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Skills/CLI/axe/SKILL.md` around lines 33 - 39, Minor readability tweaks: add
missing commas in the "AXe vs XCUITest — different event models" section to
improve flow — e.g., after introductory clauses and before contrasting phrases.
Edit the paragraph(s) mentioning AXe's HID touch events, XCUITest's
`element.tap()` / `UIAccessibilityActivate`, and the sentence advising to
"Switch to `app.debugDescription`..." to insert commas where natural (e.g.,
after "Conversely," "When AXe shows 'it works' but XCUITest fails," and similar
introductory or parenthetical phrases) so the text reads more clearly without
changing technical meaning.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@Skills/CLI/axe/SKILL.md`:
- Around line 33-39: Minor readability tweaks: add missing commas in the "AXe vs
XCUITest — different event models" section to improve flow — e.g., after
introductory clauses and before contrasting phrases. Edit the paragraph(s)
mentioning AXe's HID touch events, XCUITest's `element.tap()` /
`UIAccessibilityActivate`, and the sentence advising to "Switch to
`app.debugDescription`..." to insert commas where natural (e.g., after
"Conversely," "When AXe shows 'it works' but XCUITest fails," and similar
introductory or parenthetical phrases) so the text reads more clearly without
changing technical meaning.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 04ccac75-18e9-40e1-a19a-a6d23edfc509

📥 Commits

Reviewing files that changed from the base of the PR and between 550b3ab and 49a781b.

📒 Files selected for processing (1)

• Skills/CLI/axe/SKILL.md

[cameroncooke]

@gwillish Thanks for this, I'll need to think about this one as it's probably got a very narrow audience and I don't want to add noise to the skill. Not saying I won't add it just need to understand the problem domain myself and the number of users this will be useful for. What I don't want to do is confuse agents.