Clue-Solver

Clue Solver Testing Suite

Coverage Priorities

The suite is intentionally logic-heavy because incorrect deductions damage trust faster than ordinary UI bugs.

1. Solver correctness
2. Replay, undo, resume, and persistence
3. Edition and catalog integrity
4. Setup and turn-entry flow safety
5. UI smoke coverage and accessibility regression checks

Current Test Layers

Swift Testing domain, regression, and integration coverage

ClueSolverTests/DeductionEngineTests.swift

• Rule/invariant suites for suggestions, accusations, disjunctions, contradictions, failed accusations, envelope feasibility, and probability normalization
• Replay equivalence checks using EngineSnapshot
• Oracle comparisons against a slow reference solver on tiny editions
• Seeded random transcript coverage for solver/oracle alignment
• Invariance checks for rotated player seats and renamed cards
• Edition catalog validation
• Persistence and undo/redo integration tests with in-memory ModelContainer

ClueSolverTests/DeductionEngineTests.swift also includes:

• Announcement identity and replay suppression tests
• Card marker narrowing tests (markers update as ownership eliminates options)

ClueSolverTests/AppInfrastructureTests.swift

• AppState settings persistence
• UI-testing mode determinism
• Setup draft preservation across edition changes
• Resume-game undo enablement for saved history
• Custom edition registry save/reload/delete round-trip
• Export report coverage

XCTest UI coverage

ClueSolverUITests/ClueSolverUITests.swift

• Create investigation
• Record a suggestion and proof
• Record a wrong accusation
• Undo
• Exit and resume
• Settings flow smoke coverage
• Seeded contradiction banner and details
• Accessibility audit on home flow
• Dashboard smoke coverage while dashboard-specific accessibility issues are tracked separately

XCTest performance coverage

• initializeGame
• app launch
• saved-games fetch
• processTurn
• rebuildFromTurns
• Master Detective-sized rebuildFromTurns
• edition catalog decoding

Recommended Commands

Logic Fast

Run solver, regression, oracle, persistence, and performance tests without the UI suite:

xcodebuild test \
  -project ClueSolver/ClueSolver.xcodeproj \
  -scheme ClueSolver \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  -skip-testing:ClueSolverUITests

UI Smoke

Run the UI suite by itself:

xcodebuild test \
  -project ClueSolver/ClueSolver.xcodeproj \
  -scheme ClueSolver \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  -only-testing:ClueSolverUITests

Full Regression

Run the full unit, integration, UI, oracle, and performance suite:

xcodebuild test \
  -project ClueSolver/ClueSolver.xcodeproj \
  -scheme ClueSolver \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

Suggested CI Matrix

PR-Fast

• Logic Fast
• optionally add one smoke UI test target if PRs often touch setup/navigation

Nightly-Full

• Full Regression

Release Candidate

Run the full suite on both iPhone and iPad destinations, then add at least one physical-device pass for launch and accessibility sanity.

Remaining Gaps

• The dashboard accessibility audit is not currently CI-gated. The confirmed issues are tracked in Docs/dashboard-accessibility-issues.md until the visual redesign is addressed.
• The suite is organized into logical suites inside the existing test targets, not yet into separate physical targets such as ClueSolverOracleTests or ClueSolverRegressionTests.
• Transcript/oracle scenarios are currently code-driven rather than stored as external fixture files, so long-form historic regression playback can still be expanded.
• Xcode .xctestplan files are not yet checked into the repo. The commands above work today, but formal test plans would make CI/local workflows easier to standardize.
• There is no snapshot/golden UI layer yet. That is optional, but it would help if the design system starts changing rapidly.