Smart TV app testing checklist: 12 checks

A TV app can pass every phone test and still be unusable from a sofa. There is no touch: everything happens through focus, a handful of remote keys and an on-screen keyboard, and each TV platform does those three things its own way. The checklist below is written for streaming and other TV apps.

In VibeView, Apple TV runs as a simulator, Android TV as an emulator, and Roku sessions stream a physical Roku device. Fire TV apps built on Fire OS are tested as Android TV apps. All of them open from the Devices page in a browser tab, and all of them respond to the same keys on your keyboard: arrow keys move focus, Enter selects, and Escape is Back.

The checklist at a glance

#	Check	How to check it in VibeView
1	First focus on every screen	Open the screen; the UI Tree Inspector names the focused element
2	Focus order and reachability	Walk each row with the arrow keys; record the walk as a test
3	Back behavior	Press Escape from each screen; add a Verify step for where it lands
4	Remote keys beyond the D-pad	Use the player’s own controls; on Roku, AI steps can also press play, rewind and forward
5	Text entry and sign-in	Type into a focused field; save credentials as secret test data
6	Parental and purchase PINs	Store the PIN as a secret; verify the screen it unlocks
7	Deep links	open-url on Apple TV and Android TV; launch params on Roku
8	Resume and relaunch	Pick a start state per test or group
9	Playback screens	Verify steps on the player, then the run’s video and app log
10	Accessibility basics	Check labels in the UI Tree Inspector
11	Every TV platform you ship	Run one test on several TV devices at once
12	CI and nightly runs	vibeview run-suites with the TV platform, or a schedule

1. First focus on every screen

What to look for. When a screen opens, one usable control has visible focus. A screen with no focus, or focus on something hidden behind an overlay, leaves the viewer pressing keys at nothing.

How to check it. Open the screen in a live session and look for the highlight. Then open the UI Tree Inspector: on Apple TV and Android TV a Focused line names the element that holds focus. If the device’s accessibility layer can’t see your app’s focus, the tree shows no focused element. That’s worth knowing before you automate (see check 2).

2. Focus order and reachability

What to look for. Every control can be reached with the D-pad, Left and Right move between neighbors in a predictable order, Up and Down land on the row you expect, and focus never disappears or gets trapped at the edge of a row.

How to check it. Walk each row slowly with the arrow keys, then repeat at the speed a person uses a remote. Once the walk is right, record it: choose Create test, then Record. Each press you record remembers the element that held focus, and replay moves focus to that element and checks it arrived, rather than re-sending the key and hoping. If a row gains or loses a tile later, the test still targets the right one.

One limit to plan for: on Android TV, an app that keeps focus only in its own JavaScript (rather than react-native-tvos or Leanback focus) gives replay nothing to verify, so those steps fall back to the recorded key presses and are marked unverified. On Roku, when a channel draws its own highlight, VibeView can’t see which item is focused, so those steps are replayed by key presses unless the channel is built with the VibeView Roku plugin. The platform walkthroughs go deeper: tvOS focus and Android TV D-pad.

If you would rather not record at all, describe the steps in plain English and run them AI only, or let Explore (beta) wander the app looking for problems. Smart runs replay what was recorded and use the AI (beta) only where the screen changed or a step has no path yet. Runs in No AI mode use no usage credit.

3. Back behavior

What to look for. Back from a detail page returns to the list with focus on the item you opened, Back closes an overlay before it leaves the screen, and Back on the first screen does what your platform’s guidelines expect.

How to check it. Press Escape from every screen in the flow. In a test, add a step such as “Verify the Continue Watching row is focused” after the Back press, so a regression fails the run instead of passing silently.

On Roku, VibeView keeps the session inside your channel. A Roku leaves the channel on an unhandled Back, so if you press Back on your first screen, VibeView restarts the channel a couple of seconds later. That restart is the session bringing your app back, not a crash.

4. Remote keys beyond the D-pad

What to look for. Play/pause, rewind, fast-forward and the info or options key do something sensible on every screen, and Home is not needed to get out of a stuck state.

How to check it. The on-screen remote beside a TV session has the D-pad, Back and Menu (Options on Roku), but no media keys. On Apple TV and Android TV, check play/pause and seeking through your player’s own on-screen controls with the D-pad. In AI test steps (beta) on Roku, the AI can also press play, rewind, forward, replay and info, so a step like “Press play and verify the pause control appears” works there. On Apple TV and Android TV the AI can press Home, but only does so when a step needs to leave the app.

5. Text entry and sign-in

What to look for. Search and sign-in fields open their keyboard, accept the full value (including symbols in a password), and keep focus sensible after the keyboard closes.

How to check it. In a live session, type from your own keyboard into a focused field, or into a Roku on-screen keyboard: printable keys reach the field on every TV platform, and Backspace deletes. When an AI step or the CLI’s type command types into a focused Android TV field, VibeView opens its keyboard first.

Many TV apps draw their own keyboard, a grid of letter keys with no text field behind it. On Apple TV, the AI (beta) types on those grids itself: it moves focus to each key and selects it, switches letter case when the keyboard has a case key, and switches to the number or symbol page when it needs one.

Save the test account as test data and refer to it in steps as {{email}} and {{password}}. Mark the password secret: it is masked in results and logs and never put in the AI’s prompts. Screenshots and the run’s video are not masked, so prefer a password field that hides its text.

6. Parental and purchase PINs

What to look for. The PIN prompt appears when it should, a wrong PIN is refused with a clear message, and the right PIN opens the right profile or purchase.

How to check it. Store the PIN as a secret too. A Verify step can’t check a secret, so check the screen the PIN leads to (“Verify the Kids profile is open”) rather than the digits. A secret shorter than 6 characters, like a 4-digit PIN, is masked only where it stands on its own.

7. Deep links

What to look for. A link to a title opens that title’s page (or starts playback, if that is the contract), signed in or not, and Back from there goes somewhere sensible.

How to check it. On Apple TV and Android TV, open a link into your app from an AI step or with vibeview open-url. On Apple TV only your app’s own URL scheme is accepted, and when tvOS asks “Open in …?” for your app, VibeView answers Open. On Roku, pass launch params: they reach your channel as arguments in Main, which is where Roku delivers a deep link’s contentId and mediaType. Every value arrives as a string.

8. Resume and relaunch

What to look for. The app reopens where it should after a restart, signed-in state survives a restart but not a reinstall, and a first launch shows onboarding once.

How to check it. Each test or group has a start state: Restart the app keeps login and saved data, Clean app data opens the app as if just installed, and Fresh install reinstalls it. Run the same flow under each. On Roku, Clean app data and Fresh install both remove and reinstall the channel, because reinstalling is the only way a Roku drops a channel’s saved data. Every Roku session also starts clean, so sign-in never carries over between sessions.

9. Playback screens

What to look for. The player opens on the title you chose, its controls appear and respond, captions and audio options open, and leaving the player returns to the right place.

How to check it. Write the checks as Verify steps on what the player shows (“Verify the player shows the episode title and a pause control”). After the run, the run page plays the run’s video, marked with each step’s start time, and Logs shows your app’s log for the run. Videos are kept for 30 days, and if a recording fails the run shows its final screen instead. On Apple TV and Android TV, the system’s own messages (media codecs among them) are hidden by default and Show system lines brings them back. You can also listen: turn on sound on Apple TV (tvOS 18 and later), Android TV and Roku from the Device tab.

What this doesn’t cover: VibeView checks your app’s screens and behavior; it does not measure stream quality, bitrate switching or start-up time, and it does not validate DRM. Keep a pass on physical hardware for those before release.

10. Accessibility basics

What to look for. Every focusable button and tile has a label, the focus highlight is easy to see from across a room, and text is readable at TV distance.

How to check it. Select elements in the UI Tree Inspector and check each one has a meaningful label rather than an empty one or a file name. On Android TV the inspector also shows whether an element can take focus. Judge the highlight and text size by eye in a live session, ideally full screen. A visual check on a step catches a changed focus ring or missing element on the next build.

11. Every TV platform you ship to

What to look for. The same flow works on each TV platform, not just the one the developer uses every day.

How to check it. In the Run dialog, tick several TV devices and run the test on all of them at once. A test recorded on Apple TV replays on Android TV and the other way round. When both apps give an element the same test ID (in react-native-tvos, the same testID), the steps are focus-verified on both sides. Without shared identifiers, replay falls back to D-pad keys and marks the step unverified. Link your Apple TV, Android TV and Roku apps as one product on the app page so their tests appear together and share test data.

12. CI and nightly runs

What to look for. TV tests run on every build, not only before a release.

How to check it. Tag your TV groups and run them from your pipeline with vibeview run-suites, using --platform tvos, --platform androidtv or --platform roku (see CI testing). Roku channels have no cloud builds, so package the channel zip in your own job and upload it. Or schedule a group to run every night or on each new build, and get the result without opening a terminal.

Run the checklist on your own build

Testing a whole streaming service, phones included? See OTT & streaming app testing for how the pieces fit together.

Frequently asked questions

Do I need a TV or a streaming box to use this checklist?

No. Apple TV and Android TV run as a simulator and an emulator in the cloud, and Roku sessions stream a physical Roku device to your browser. You still want a hardware pass for remote feel, stream quality and DRM before release.

Does it work for Fire TV apps?

Fire TV apps built on Fire OS are Android apps, so you test them as Android TV apps. Amazon services such as the Appstore and in-app purchasing are not available, and apps built for Vega OS are not supported. To publish one, see Submit a Fire TV app to the Amazon Appstore.

Can one test run on Apple TV and Android TV?

Yes. A recording made on one replays on the other. When both apps use the same test IDs, replay verifies focus on both; without them the steps replay as D-pad keys and are marked unverified.

How do I test sign-in without putting the password in the test?

Save it as secret test data and refer to it as a placeholder in the step. VibeView types the real value on the device, masks it in results and logs, and never puts it in the AI’s prompts.