Testing workout audio cues: calls, Siri, Bluetooth and the podcast that never resumes

Audio cue bugs do not live in the cue. They live in transitions: the screen locking, a call arriving, Siri listening, a podcast that should pause and resume, an earbud falling out, an Android build targeting a newer API level. A desk test with the screen on and nothing else playing triggers none of them. So the test plan is a list of documented platform events, each caused on purpose, each with an expected result taken from the platform's own documentation.

This page is that list. Each row links to the page that explains the behaviour.

What can be unit-tested, and what cannot#

Split the cue system in two. The decision ("given the workout time, the prompt style, whether focus was granted and whether headphones are connected, should this cue be speech, a tone, a haptic or nothing?") is a pure function. Test it exhaustively in your normal suite, alongside the rest of test. The delivery, meaning the session, focus, route and engine, can only be tested on a device, because every interesting input comes from the operating system.

enum CueOutput { case speech, tone, haptic, skip }

func output(promptStyle: AVAudioSession.PromptStyle,
            headphonesConnected: Bool,
            speakerOptIn: Bool) -> CueOutput {
    switch promptStyle {
    case .none:   return .haptic
    case .short:  return .tone
    default:      return (headphonesConnected || speakerOptIn) ? .speech : .haptic
    }
}

The mapping from promptStyle comes from Apple's descriptions of the three styles, set out on the AVSpeechSynthesizer page. The headphones branch is our judgement from the route-change page.

The iOS device matrix#

The last row is a test Apple documents directly. The mediaServicesWereResetNotification page: "You can trigger a media server reset by choosing the "Reset Media Services" selection under the Developer menu in the iOS Settings app. Using this utility helps to ensure that your app responds appropriately if media services were reset." Most audio code has never been through it.

The Android device matrix#

Two Android rows depend on the OS version, so run them on at least one device below Android 12 and one on Android 12 or later: Google's guide says audio focus is "not managed by the system" before Android 12, and the forced fade-out and call mute arrive with it.

Logging that makes field reports useful#

The matrix catches what you can cause. Field reports catch the rest, but only if the log has the inputs. Our judgement on what to log per cue, on both platforms:

• scheduled time and actual time played, or why it was skipped
• the focus request result on Android, or whether activation threw on iOS
• promptStyle on iOS
• the current output route
• app state: foreground or background, and on Android whether the foreground service was running

With those five fields, most "the coach went quiet" reports can be matched to a row in one of the tables above.

Who should run it#

Run the matrix on real devices, with the screen locked, for a full workout, not in short bursts with the screen on. That is our recommendation, not something either platform states. The device-lab mechanics are in device lab and CI; watch-specific setup is in testing watch apps; and accessibility testing of the same flows, including a screen reader talking over your cues, is in testing accessibility.

Monday morning#

Extract the cue decision into a pure function and give it a table-driven test. Print the two device matrices and walk one device through each before the next release, starting with Reset Media Services on iOS and a screen-off cue on an Android build targeting API level 35. Add the five log fields. Then hand the matrix to whoever does release testing, because none of these rows will ever fail on a developer's desk.