docs(ios-ui-tests): document terminate-after-navigation race + when to use direct tap vs helper

[auerbachb]

Following #319 (closes #318) we landed a fix for the iOS smoke-lane flake in `testLaunchLoginCompleteSessionAndHistoryPersistence`. The investigation surfaced a non-obvious pitfall that is worth pinning to repo docs so future test authors do not re-discover it.

The pitfall

When a UI test calls `XCUIApplication.terminate()` shortly after triggering navigation (e.g., immediately after a button `.tap()` that starts a new screen), `launchd` on macos-26/iOS 26 simulators sometimes loses the process and surfaces `Failed to terminate ... :0` after a long hang. Original failing-runs evidence: `25215904325`, `25216409703`, `25216402153`, `25216777439`.

Why the obvious helper isn't always the right call

The natural reach is for the existing `tap(_:thenWaitForRoot:in:)` helper at `ios/StillPointAppUITests/StillPointAppUITests.swift:396`. But that helper composes `tapByStableCenter` (8s stable-frame check) with a 12s root-existence wait, and `tapByStableCenter` returns `false` without tapping if the element's frame doesn't pass the stability check. In one specific flow (post-login → home → Begin) the home button frame failed that check; the helper retried 3× and never registered a tap. Evidence: PR #319 v1 (`d9e69aa`) failed CI on run 25218186115 with `StillPointAppUITests.swift:404: error: ... Expected tap to transition to root.currentView.session`.

The shipping fix on `main` (`ddf7b69`) keeps direct `beginButton.tap()` and adds an explicit `waitForExistence` for the destination root before `terminateAppReliably` — same idle-before-terminate benefit, no change to tap semantics.

What we want documented

Add a "Patterns and pitfalls" section to `ios/StillPointAppUITests/README.md` so future test authors have a clear rule. Concretely:

• One short entry: "Wait for the destination root before terminating after navigation."
• Explain the launchd race (terminate during navigation/audio init).
• Show the "good" pattern (direct `.tap()` + `waitForExistence("root.currentView.")` before `terminateAppReliably`).
• Note when `tap(_:thenWaitForRoot:in:)` is fine (already-quiescent flows: rotation/VoiceOver tests use it successfully) and when it can bite (post-login transitions where the destination element's frame is briefly unstable).
• Cite the actual file/line pointers and PR/run IDs so the rationale is auditable.

Acceptance criteria

• New `## Patterns and pitfalls` section added to `ios/StillPointAppUITests/README.md`
• Section explains the terminate-after-navigation race in plain English
• Section gives the canonical "good" pattern with a Swift snippet
• Section explains when the `tap(_:thenWaitForRoot:in:)` helper is OK vs not
• Section links to PR fix(ios-e2e): wait for session root before terminate to avoid launchd race #319 and the relevant failing/passing run IDs for traceability
• No code changes outside `ios/StillPointAppUITests/README.md`

Implementation Plan

Source: Claude's analysis. CodeRabbit plan requested but doc-only changes typically don't need a planner round-trip; will incorporate any CR feedback during PR review.

File

• ios/StillPointAppUITests/README.md (only)

Insertion

A new ## Patterns and pitfalls section, placed after ## CI setup de-duplication notes and before ## VoiceOver smoke steps (manual fallback). ~50 lines.

Section structure

1. Heading ## Patterns and pitfalls
2. Subsection: Wait for the destination root before terminating after navigation
   • Plain-English explanation of the launchd race (failure signature Failed to terminate ... :0)
   • "Do this" Swift snippet using direct .tap() + waitForExistence("root.currentView.<slug>") + terminateAppReliably
   • "Don't do this" counter-example
3. Subsection: When tap(_:thenWaitForRoot:in:) is fine vs when it bites
   • Brief description of what the helper does (tapByStableCenter 8s stable-frame check + 12s root wait, 3× retry)
   • The trap: stable-frame check returns false silently when source element frame is briefly unstable (post-transition), helper retries 3× without ever tapping
   • Concrete evidence: PR #319 v1 commit d9e69aa failed run 25218186115; shipping fix ddf7b69 keeps direct .tap()
   • Rule of thumb: helper for already-quiescent flows; direct .tap() + explicit wait right after a transition

Out of scope

• No code changes to StillPointAppUITests.swift or any product code
• Not adding a lint rule / CI check (separate ticket if desired)
• Not updating docs/testing/e2e-policy.md — its Section 3 already mandates "XCTest expectations/predicate waits" at the policy level; this README is the how-to for iOS specifically

Verification

• Local coderabbit review --prompt-only clean
• Open PR with Test Plan; CodeRabbit + BugBot review; merge after gate met (per repo policy)

[github-actions]

@coderabbitai plan

[auerbachb]

@coderabbitai plan

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

🔗 Related PRs

#261 - Add iOS Release-config UI test gate to TestFlight workflow (#253) [merged]
#277 - Fix iOS UI test auth-screen flake (#276) [merged]
#300 - fix(ios): UITest tapAndType waits for keyboard focus (#288) [closed]
#302 - docs(ios): canonical App Store metadata + copy audit (#195) [closed]
#319 - fix(ios-e2e): wait for session root before terminate to avoid launchd race [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Single-file documentation update to ios/StillPointAppUITests/README.md
• Captures institutional knowledge from PR #319 investigation in a discoverable location
• Provides actionable guidance with code snippet and clear "when to use" rules
• Includes full traceability to original issues, PRs, and CI runs for future auditing

Implementation Steps

Document Terminate-After-Navigation Pattern in README

Add a new documentation section to the UI tests README that captures the learnings from the PR #319 investigation, providing clear guidance for future test authors on avoiding the launchd termination race.

Add "Patterns and pitfalls" Section to README

Add a new ## Patterns and pitfalls section to ios/StillPointAppUITests/README.md that documents the terminate-after-navigation race and provides clear guidance on tap helper usage.

• Place the new section logically within the existing README structure (after the test coverage/environment sections, before CI-specific sections)

• Create a subsection explaining the terminate-after-navigation race:

  • Describe the symptom: launchd on macOS-26/iOS 26 simulators can lose the process when terminate() is called shortly after triggering navigation
  • Explain the root cause: terminating during navigation/audio initialization races launchd, producing "Failed to terminate ... :0" after a long hang
  • Reference the original failing runs: 25215904325, 25216409703, 25216402153, 25216777439

• Document the canonical "good" pattern with a minimal Swift snippet showing:

  • Direct button.tap() call
  • waitForExistence on the destination root element (e.g., root.currentView.session)
  • Then terminateAppReliably(app)
  • Reference the implementation at StillPointAppUITests.swift lines 69-78 as the canonical example

• Add guidance on when to use each tap approach:

  • tap(_:thenWaitForRoot:in:) helper: appropriate for already-quiescent flows (rotation tests, VoiceOver tests) where element frames are stable
  • Direct .tap() + explicit waitForExistence: required for transitions where destination element frames may be briefly unstable (e.g., post-login → home → Begin flow)
  • Explain why: tapByStableCenter returns false without tapping if the frame fails stability checks, causing silent tap failures

• Include traceability links:

  • Link to PR #319 (the fix)
  • Link to Issue #318 (the original bug)
  • Reference the failed CI run 25218186115 that showed why the helper approach didn't work
  • Reference commit ddf7b69 as the shipping fix on main

🤖 Prompt for AI agents

Update `ios/StillPointAppUITests/README.md` by inserting a new `## Patterns and
pitfalls` section. Place it after the test coverage/environment sections and
before any CI-specific sections.

The section should include the following subsections and content:

**Terminate-after-navigation race subsection:**
- Symptom: `launchd` on macOS-26/iOS 26 simulators can lose the process when
`terminate()` is called shortly after triggering navigation
- Root cause: terminating during navigation/audio initialization races launchd,
producing `"Failed to terminate ... :0"` after a long hang
- Reference the original failing CI runs: `25215904325`, `25216409703`,
`25216402153`, `25216777439`

**Canonical "good" pattern subsection:**
- Include a minimal Swift code snippet demonstrating:
  1. A direct `button.tap()` call
2. `waitForExistence` on the destination root element (e.g.,
`root.currentView.session`)
  3. Then `terminateAppReliably(app)`
- Note that the canonical example lives at `StillPointAppUITests.swift` lines
69–78

**When to use each tap approach subsection:**
- `tap(_:thenWaitForRoot:in:)` helper: appropriate for already-quiescent flows
(rotation tests, VoiceOver tests) where element frames are stable
- Direct `.tap()` + explicit `waitForExistence`: required for transitions where
destination element frames may be briefly unstable (e.g., post-login → home →
Begin flow)
- Explain why: `tapByStableCenter` returns `false` without tapping if the frame
fails stability checks, causing silent tap failures

**Traceability links subsection:**
- Link to PR `#319` (the fix)
- Link to Issue `#318` (the original bug)
- Reference failed CI run `25218186115` that showed why the helper approach
didn't work
- Reference commit `ddf7b69` as the shipping fix on `main`

Research

The iOS UI test suite lives in ios/StillPointAppUITests/ with three files: the main test file StillPointAppUITests.swift, a helper extension, and README.md. The README currently has sections covering reference simulator specs, test coverage mapping, environment knobs, local run commands, CI lane plans, and VoiceOver manual steps—but no "Patterns" or "Pitfalls" documentation exists anywhere in the ios/ directory. The test file contains several stability helpers: tap(_:thenWaitForRoot:in:) which combines tapByStableCenter (8s frame stability check) with a 12s root-existence wait, and terminateAppReliably which retries termination up to 4 times with 15s polling per attempt.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Update `ios/StillPointAppUITests/README.md` by inserting a new `## Patterns and
pitfalls` section. Place it after the test coverage/environment sections and
before any CI-specific sections.

The section should include the following subsections and content:

**Terminate-after-navigation race subsection:**
- Symptom: `launchd` on macOS-26/iOS 26 simulators can lose the process when
`terminate()` is called shortly after triggering navigation
- Root cause: terminating during navigation/audio initialization races launchd,
producing `"Failed to terminate ... :0"` after a long hang
- Reference the original failing CI runs: `25215904325`, `25216409703`,
`25216402153`, `25216777439`

**Canonical "good" pattern subsection:**
- Include a minimal Swift code snippet demonstrating:
  1. A direct `button.tap()` call
2. `waitForExistence` on the destination root element (e.g.,
`root.currentView.session`)
  3. Then `terminateAppReliably(app)`
- Note that the canonical example lives at `StillPointAppUITests.swift` lines
69–78

**When to use each tap approach subsection:**
- `tap(_:thenWaitForRoot:in:)` helper: appropriate for already-quiescent flows
(rotation tests, VoiceOver tests) where element frames are stable
- Direct `.tap()` + explicit `waitForExistence`: required for transitions where
destination element frames may be briefly unstable (e.g., post-login → home →
Begin flow)
- Explain why: `tapByStableCenter` returns `false` without tapping if the frame
fails stability checks, causing silent tap failures

**Traceability links subsection:**
- Link to PR `#319` (the fix)
- Link to Issue `#318` (the original bug)
- Reference failed CI run `25218186115` that showed why the helper approach
didn't work
- Reference commit `ddf7b69` as the shipping fix on `main`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!