Automating Android TV app with Nightwatch
Tags: mobile, tv, automation, appium
Published: 2024-04-25 08:07:46

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](https://appium.io/docs/en/2.0/quickstart/install/), the automation framework for mobile & TV apps and Nightwatch runs at the back of this.
- [Android Studio & SDK tools](https://developer.android.com/studio), 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
![TV emulator](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/d61n3wmd7k3fyeu1s0vo.png)
- [Java JDK & runtime](https://www.java.com/en/download/apple.jsp), as required for any Android activities
- [Nightwatch](https://nightwatchjs.org/) 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`:
```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":

![appActivity](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/es2futz8yroo62olzsfx.png)


The test / spec file `nav.spec.js`:
```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](https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_CENTER) 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](https://github.com/appium/appium-inspector/releases) or use the [browser version](https://inspector.appiumpro.com/).

I also joined the Nightwatch [Discord channel](https://discord.com/channels/618399631038218240/1227865365053313114) to ask questions as I had hiccups along the way.

Enjoy! 🎉