Automating Android TV app with Nightwatch

I joined a company that recently introduced a TV app 📺 for their platform. A curious cat 😺 like I am, I raised my hand and immediately jumped into finding ways to automate this piece of art. It is highly similar to Mobile apps but simple clicks and double taps just won't work, we need to use the Directional Pads (DPAD) 🎛️ and their relevant values (aka remote control for TV's).

I did some googling (aka 'research' in the digital world) and long story short, I ended up using Nightwatch 🦉 since we are also planning to launch it with Apple TV. Hence, there are advantages of having a single tool to automate both.

First, we need to install 🚀 the following:

• Appium, the automation framework for mobile & TV apps and Nightwatch runs at the back of this.
• Android Studio & SDK tools, IDE used for building and testing Android apps and used to create a TV app emulator
• Create a TV app emulator from Android Studio via Device Manager
• Java JDK & runtime, as required for any Android activities
• Nightwatch which will prompt to create a boilerplate framework specifically for Mobile / TV apps.
• Create a new folder called apps and place the .apk file there (this is the working package and if you don't have it, ask your friendly dev to give it to you).

Then, we need to build the test scripts in the project directory.
The configuration file: nightwatch.conf.js:

  'app.android.emulator': {
      extends: 'app',
      'desiredCapabilities': {
          // More capabilities can be found at https://github.com/appium/appium-uiautomator2-driver#capabilities
          browserName: null,
          platformName: 'android',
          // `appium:options` is not natively supported in Appium v1,but works with Nightwatch.
          // If copying these capabilities elsewhere while using Appium v1,make sure to remove `appium:options`
          // and add `appium:` prefix to each one of its capabilities,e.g. change 'app' to 'appium:app'.
          'appium:options': {
          automationName: 'UiAutomator2',
          // Android Virtual Device to run tests on
          avd: 'TV_1080p',
          orientation: 'PORTRAIT',
          // While Appium v1 supports relative paths,it's more safe to use absolute paths instead.
          // Appium v2 does not support relative paths.
          app: `${__dirname}/apps/tv-app.apk`,
          appActivity: 'com.tv.app.MainActivity', // include this if app does not start on its own - 
          // chromedriver executable to use for testing web-views in hybrid apps.
          // add '.exe' at the end below (making it 'chromedriver.exe') if testing on windows.
          chromedriverExecutable: `${__dirname}/chromedriver-mobile/chromedriver`,
          newCommandTimeout: 0
          }
      }
  },

NOTE: if you don't know the value for appActivity, open the .apk file in Android Studio then look for AndroidManifest.xml then search for "activity":

The test / spec file nav.spec.js:

describe('navigate the menus', function() {
    test('should be able to navigate left menu', async function(app) {
        await app.appium.pressKeyCode(20) // presses down once
            .waitForElementVisible('xpath', '//android.widget.TextView[@text="Search"]')

        await app.appium.pressKeyCode(20)  // presses down once
            .waitForElementVisible('xpath', '//android.widget.TextView[@text="Settings"]');

        await app.appium.pressKeyCode(23) // presses the centre pad to close the left menu again
            .waitForElementNotPresent('xpath', '//android.widget.TextView[@text="Home"]');
    });

    // guide on DPADS keys which you can place in a page object file
    // dpadCenter: 23,
    // dpadLeft: 21,
    // dpadRight: 22,
    // dpadUp: 19,
    // dpadDown: 20
});

NOTE: As mentioned earlier, to simulate real user experience, you need to use the remote or directional pads. Refer to this guide for the complete numeric values.

Lastly, we need to test and run if the automation actually works:

• Run appium from a separate terminal with the same command
• Open another terminal then open the newly-created emulator with the command emulator -avd TV_1080p
• Run the test with npx nightwatch tests --env app.android.emulator and watch it work! 🎮

To inspect elements, it is recommended to download the Appium Inspector or use the browser version.

I also joined the Nightwatch Discord channel to ask questions as I had hiccups along the way.

Enjoy! 🎉

Comments

[Daniel Martin]

This is awesome — thanks for sharing such a detailed walkthrough! Automating Android TV apps isn’t something you see documented often, especially using Nightwatch in combination with Appium. Most teams I’ve seen stick to Appium alone or jump into custom frameworks, so this unified setup for both Android TV and Apple TV makes a lot of sense.

I ran into something similar when testing an OTT app a while back — the biggest pain point was definitely handling DPAD navigation. Using pressKeyCode was reliable, but debugging focus states on TV UIs took a bit of trial and error. I like that you’ve added those DPAD key references directly in the spec; that’s super helpful for anyone new to TV automation.

One thing that might be worth experimenting with (if you haven’t already) is adding page object patterns for your navigation flow. It makes the tests much easier to maintain, especially when your app grows or the menu hierarchy changes. Also, Appium Inspector is a life-saver for TV layout debugging — I second that recommendation.

By the way, have you tried testing the same setup with a real Android TV device instead of the emulator? In my experience, DPAD inputs sometimes behave slightly differently depending on the TV brand or remote firmware. Would love to hear if you’ve seen similar quirks in your setup.