28 Apr 2025.

Tags: Device Setup Test Development

Today we have published improvements to Stb-tester’s Object Repository to better support testing the same device or app across different territories, languages, and software releases. We have also improved the way that the Stb-tester Portal web interface displays information about each device in your test farm.

We have always recommended specifying the device type (e.g. “appletv”) in the Node-specific config file of each Stb-tester Node, in the device_under_test.device_type configuration key. This was a free-form field that you can read in your test scripts to make decisions such as which reference images to use, OCR language, etc.

Today we are broadening that recommendation to an entire configuration section called “device_profile”. This section is treated specially in the following ways:

  1. When you save a screenshot to the Object Repository, Stb-tester will record the entire device_profile config section (copied from the Node-specific config file of the Node where the screenshot came from) as well as the device_under_test.device_type and ocr.lang config values. This allows the Object Repository to use the correct OCR language for that screenshot when testing your Page Objects; and your Page Object properties can read other values from this section.
  2. For convenience, the Stb-tester Portal web interface can show the device_type or selected values from the device_profile configuration of each Node in the Nodes menu, the “video wall” or “virtual NOC” page, and the admin page. This is controlled by the new test_pack.node_label_format setting.

We have also changed the way that the node.friendly_name configuration is displayed in the Stb-tester Portal web interface:

  1. The Node’s “friendly name” is now taken from the config files on the current git branch — previously the web interface always showed the friendly name from the main branch.
  2. Similarly, editing the Node’s “friendly name” in the admin page will write the new value to the config files on the current git branch, instead of the main branch.

Changes 3 & 4 were made for consistency with the new node_label_format and with the existing behaviour of stbt.get_config("node", "friendly_name") when running a test script. This only affects the web interface; the friendly_name value in the response of the /api/v2/nodes REST API endpoint is always taken from the main branch (no change in behaviour there, as it’s a public API).

Motivation: Configuration for the Object Repository

When you run a test script against a real device, you might need to configure certain settings differently depending on the device. For example, if you are testing devices in different territories, you need to configure the language for OCR. This is done through the Node-specific config files, which are files named after the serial number of each Stb-tester Node, like this:

config/test-farm/stb-tester-xxxxxxxxxxxx.conf

[device_profile]
name = Roku Mexico
[ocr]
lang = spa

When you run a test, the configuration is loaded to match the Node that is running the test. This is true for Stb-tester APIs such as stbt.ocr which reads the “lang” setting, and it’s true for configuration that you read explicitly by calling stbt.get_config.

However, when you are testing your Page Object code in the Object Repository, the code isn’t running on any particular Node; instead of a live device-under-test the Page Object code is tested against a screenshot. You want the configuration (such as OCR language) to match the device the screenshot came from. When you save a screenshot to the Object Repository, Stb-tester automatically records the following configuration:

  • ocr.lang
  • device_under_test.device_type
  • The entire device_profile section

This configuration is saved into a “.conf” file next to the screenshot (for example selftest/screenshots/roku/Menu/screenshot.png.conf).

We don’t copy all of the configuration, only the above values, to minimize maintenance overhead. The Object Repository will continue to read common configuration (in .stbt.conf) from the current values on the selected branch; whereas the above values are frozen in time when you save the screenshot.

To recap:

When you run a test, calling stbt.get_config will read from these files on the git branch that you are running the test from:

  • .stbt.conf (global config)
  • config/test-farm/${node_id}.conf (the Node-specific config file for the Node running the test)

In the Object Repository, calling stbt.get_config will read from these files instead:

  • .stbt.conf (global config)
  • selftest/screenshots/${path_to_screenshot_png}.conf (recorded from the Node-specific config file at the time the screenshot was taken)

Recommendations

Any configuration that varies between different devices and needs to be read from Page Object properties, should be placed in the device_profile section of the Node-specific config file of each Node.

Note that Page Object properties should only read information from the screen (a video-frame or screenshot). They should not interact with the device-under-test, nor read information from the network. This device_profile section shouldn’t contain details about a single device (such as the device’s IP address) — that would belong in the device_under_test section. Avoiding high-cardinality values (IP addresess, serial numbers) in the device_profile section will help the Object Repository generate its data more efficiently, too.

Optionally, use the new test_pack.node_label_format setting in your global .stbt.conf file to display the device type (or any other device-specific configuration) in the Stb-tester Portal web interface.