fune/devtools/client/aboutdebugging/documentation/TESTS_REAL_DEVICES.md

Running Tests with real USB connected devices for the new about:debugging

This document explains how to test with real USB connected devices.

Tests overview

The tests that use a real device are located in devtools/client/aboutdebugging/test/browser/and the name of tests starts with browser_aboutdebugging_real. These are normal mochitest, but we need to setup the environment before starting tests.

Setup environment

Real device side

1. Enable USB debugging on your device
2. Launch Firefox
3. Enable USB debugging on your Firefox
4. Connect to your PC via USB

You can refer to https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html#connecting-to-a-remote-device

PC side

Setup the real device information to evaluate the validity in tests.

1. Copy a sample file which is located at devtools/client/aboutdebugging/test/browser/real/usb-runtimes-sample.json and rename it for example to devtools/client/aboutdebugging/test/browser/real/local-usb-runtimes.json.

2. Edit the file.

   This is a JSON file like below, write your real device information in here. This example indicates that there should be one USB device and should be displayed Pixel 2 as device name and Firefox Nightly as short name on the sidebar of about:debugging. Regarding the other information, please see Detail of config file section of this document.

[
  {
    "sidebarInfo": {
      "deviceName": "Pixel 2",
      "shortName": "Firefox Nightly"
    },
    ...
  },
  ...
]

Test

Normally, although we do test ./mach mochitest <path>, to load the real device information created, specify the path as USB_RUNTIME environment variable, then do test. For example, if the name of the saved file is devtools/client/aboutdebugging/test/browser/real/local-usb-runtimes.json, run all real device test with a command like the one below:

USB_RUNTIMES=devtools/client/aboutdebugging/test/browser/real/local-usb-runtimes.json ./mach mochitest devtools/client/aboutdebugging/test/browser/browser_aboutdebugging_real

If there is no USB_RUNTIMES environment variable, the tests will not run. This is also to avoid to run on try-server and so on.

Detail of config file

[
  {
    "sidebarInfo": {
      "deviceName": "Pixel 2", // This should display as device name on the sidebar.
      "shortName": "Firefox Nightly" // This should display as short name on the sidebar.
    },
    "runtimeDetails": {
      "info": {
        "name": "Mozilla Nightly", // This should display on the runtime info of runtime page.
        "version": "64.0a1" // This should display on the runtime info of runtime page.
      }
    }
  }
  // Of course, you can append additional USB devices. Some tests can do with multiple devices.
]