Testing and Verification

Testing and Verification

This page captures the normal validation flow for A Playa Named Gus changes.

Before Building

Regenerate the project whenever files or targets change:

xcodegen generate

Then resolve packages if needed:

xcodebuild -resolvePackageDependencies -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus'

Formatting and Static Checks

Scripts/format.sh
swiftformat Sources Tests --lint
jq empty Resources/Localizable.xcstrings
git diff --check

All new or changed user-facing strings belong in Resources/Localizable.xcstrings.

Unit and UI Tests

The A Playa Named Gus scheme is build-only — use a per-platform test scheme for the test action. The Gus <platform> Unit Tests schemes run the Swift Testing bundles only and are the lanes run in CI; the Gus <platform> Tests schemes also run the narrow launch UI test.

xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus iOS Unit Tests' -destination 'platform=iOS Simulator,name=iPhone 17'

GusTests / GusTVOSTests / GusVisionOSTests / GusMacOSTests cover shared pure logic with Swift Testing. GusUITests intentionally stays narrow and verifies that the app launches to the Connect screen.

Useful test coverage areas include:

• URL normalization and session credential keys.
• Server store persistence and public-user profiles.
• App route parsing, navigation model, and navigation preferences.
• Content deep links.
• Search and library pagination.
• Offline download state.
• Playback reporting payloads, audio playback, and up-next.
• Stream URL fallback behavior and 3D media detection.
• Provider architecture boundary.
• Content-rating gate (family safety).
• Network retry policy.
• Diagnostics, SyncPlay, remote sessions, and Top Shelf snapshots.
• Performance baselines and UI layout metrics.

Platform Build Matrix

Use -showdestinations first because simulator names and IDs change across Xcode installs:

xcodebuild -showdestinations -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus'

Then build each supported destination:

xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=iOS Simulator,name=iPhone 17' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=iOS Simulator,name=iPad Pro 11-inch (M5)' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=tvOS Simulator,name=Apple TV 4K (3rd generation)' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=macOS' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=visionOS Simulator,id=<UUID>' build

Build the watchOS companion separately:

xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus watchOS' -destination 'generic/platform=watchOS Simulator' build

Manual Verification

Automated tests do not replace device and server smoke testing. For user-facing changes, verify the relevant flow against a Jellyfin server:

• Connect, sign in, restore session, and sign out.
• Home, library, search, item detail, and series navigation.
• Video playback start, progress reporting (pause/resume report immediately), pause, seek, stop, chapters, and next-up prompt.
• Direct play of hardware-supported formats (HEVC/HDR/surround preserved) and HLS fallback for the rest.
• Audio/subtitle stream switching — instant in-place on direct-played files; server rebuild on transcodes; text subtitles ride the manifest rather than forcing burn-in.
• Episode auto-play at natural end (and the Settings → Playback toggle), player auto-dismissal when nothing is queued.
• Streaming Quality setting caps the negotiated bitrate.
• macOS dedicated player window (resizable, fullscreen-capable).
• Music and audiobook playback (queue, shuffle/repeat, speed, chapters).
• Photo, Live TV, and book browsing; EPUB reading on iOS/iPadOS.
• Now Playing artwork and remote commands.
• AirPlay/PiP where the platform supports them.
• Offline download start, progress, pause, resume, delete, local playback, and low-space handling.
• Deep links, Handoff continuation, Spotlight results, and Siri "Play media".
• Family-safety gating against the Declared Age Range.
• visionOS Gus Cinema and 3D/spatial fallback behavior.

Device-only areas:

• True stereo separation on Vision Pro.
• PiP/background audio behavior.
• AirPlay route handoff.
• CarPlay audio surface (with the entitlement granted).
• watchOS remote control, route-picker audio, battery soak, and WatchConnectivity hand-off on hardware.
• App Store signing/archive behavior.

Definition of Done

A change is not complete until:

• It builds on all five supported destinations (and the watch lane when touched), or any missing platform validation is explicitly documented.
• New strings are catalogued.
• Platform-only APIs do not leak into unsupported targets.
• New screens have loading, empty, and error states.
• Accessibility behavior is considered for VoiceOver, Dynamic Type, focus, and contrast.
• Any deviation from the native-first mandate is justified in the commit.
• Documentation/ROADMAP.md and the wiki are updated when scope or behavior changes.