Advanced configuration

Configuration files

Configuration of the stb-tester devices in your test farm is done by modifying the following files in the test-pack git repository.

  • .stbt.conf: An “ini” format file that configures your test farm and the run-time environment in which testcases are executed. See .stbt.conf below.
  • config/test-farm/<hostname>.conf (optional, for example config/test-farm/stb-tester-one-b8aeed72c37d.conf): Allows overriding configuration values for a specific stb-tester device in your test farm. The allowed values are the same as for .stbt.conf below.
  • config/remote-control/
  • config/setup/setup: An optional script to perform custom configuration of the environment in which your testcases are run. See Customising the test-run environment.


The file .stbt.conf in the root of your test-pack is a configuration file in the “ini” format that specifies the run-time environment in which testcases are executed.

By default this file is a symlink to config/stbt.conf.

stbt_version = 28
default_remote_control = roku

lang = eng
  • test_pack.stbt_version specifies the version of the stbt Python API that your testcases use. This allows pinning the test execution environment to a specific version of the stbt core Python API.

    This is different than the version of the stb-tester ONE’s user interface software (which you should always upgrade to the latest available version). Upgrading the user interface software will never introduce incompatible changes to the test execution environment.

    This allows you to manage upgrades of the stbt core Python API in a controlled manner, and to test the upgrade (by changing this setting in a branch of the test-pack git repo before committing it to the master branch). See the Release notes for the differences between these versions.

    Allowed values:

    • 0.21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
  • test_pack.default_remote_control specifies which remote control will be selected by default in the web interface, and in the run_tests REST API if you don’t specify remote_control. This is most useful in host-specific config files, when you have different stb-tester devices connected to different models of set-top boxes.

    For example if you have an infrared configuration file called roku.lircd.conf, here you would specify default_remote_control = roku.

Reading configuration values in your test scripts

You can store your own custom configuration values in the .stbt.conf and config/test-farm/<hostname>.conf files. Please use a different section name (not [test_pack]) to avoid clashes with configuration keys that we might add in the future. For example:

stb_ip =

Then you can access this configuration value in your test scripts by using stbt.get_config. For example, if your device-under-test allows retrieving logs over HTTP you might use something like this:

stb_ip = stbt.get_config("my_company_name", "stb_ip")
print requests.get("http://%s/logs" % stb_ip).text

Customising the manual remote control image

The following instructions are also available as a video here.

To add an infrared remote-control configuration see Record your remote control configuration. The following instructions are to configure a custom graphic for your remote control in the Manual control section of the stb-tester ONE’s user interface:


The available remote controls (in the drop-down list) come from the config/remote-control/*.lircd.conf files in your test-pack git repository.

When you select a remote control from the drop-down list, the stb-tester ONE displays an image of the remote control with buttons you can click to send the corresponding infrared signal to the system-under-test.

You can customise this image by creating an SVG file with the same prefix as the *.lircd.conf file. For example, if there’s an infrared configuration file called rcu123.lircd.conf, the corresponding SVG file is rcu123.svg.

You only need to do this if the stb-tester ONE’s built-in SVG doesn’t have all the buttons you need.

  1. Create a new SVG with a vector-graphics program (we recommend Inkscape).

    • Instead of starting from scratch, you can copy the stb-tester ONE’s built-in SVG.
  2. Each SVG element that will be a clickable button must have a class attribute set to the value key, and a key attribute set to the name of the key as specified in the lircd.conf file.

    For example:

    • class=key

    To do this in Inkscape: select Edit > XML Editor, then click on the element you want to edit, and add the class and key attributes.

  3. Commit the SVG image to the test-pack git repository, and use git push to push your commit to the stb-tester ONE.

Instead of drawing the remote control from scratch with vector graphics, a useful technique is to import a jpeg or png image of your remote control into the vector-graphics program. When it asks you whether to embed the image or link to it, choose “embed”. Then draw rectangles or circles on top of each button and set the attributes of these shapes as described above. These shapes must be in the foreground layer, and they must have a solid fill. However you can set the alpha channel of the fill colour to 1% which makes it effectively invisible (so that you can see the original button in the bitmap image underneath).

Customising the test-run environment

You may wish to use different Python libraries or other packages in your test scripts. For example you might want the socat program installed to collect more information from the system-under-test.

The stb-tester ONE allows you to run arbitrary commands to set-up your test environment, including installing Ubuntu packages with apt-get install and Python packages with pip. Each test job will then run in a pristine copy of the environment you design.


Save the following file into your test pack as config/setup/setup:

#!/bin/bash -ex

# Install Ubuntu packages
export DEBIAN_FRONTEND=noninteractive
sudo apt-get update
sudo apt-get install -y \
    python-requests \

# Install Python packages
sudo pip install pylint==1.3.1

Set the executable bit:

chmod a+x config/setup/setup

Commit and push your change:

git add config/setup/setup
git commit
git push

Now the first time you run a test, the setup script will be run to create the test environment and you will be able to import requests in your Python test-scripts.


  • Each test-environment will be built just before it is needed and cached so you don’t need to wait for it to be built for every test run. Cached environments are forgotten when the stb-tester ONE is powered off, so will be recreated as-needed after a reboot.

  • If you change the setup script, then a new environment will be built the next time you run a test.

  • When the setup script is run it will have no access to the rest of the test-pack sources. It will be installed into /var/lib/stbt/test-pack/config/setup/setup and executed from the working directory /var/lib/stbt/test-pack.

  • The setup script will be run in a vanilla Ubuntu 14.04 environment with stb-tester installed. The stb-tester version is determined by test_pack.stbt_version in .stbt.conf.

  • The setup script must return a non-zero exit status if it fails to set up the environment correctly (for example if it is a shell script, use set -e).

  • images/v27.3-job-logs.png

    If the setup script fails no tests will be run. To see the output from the setup script click the “Logs” link.

  • You can test your setup script by running stbt-docker from a checkout of the test-pack on your PC.

Upstream git server

If you have a git server in-house (on the same network as your stb-tester ONE devices) you can host the test-pack repository on that server, and configure the server with a post-receive hook to update all the stb-tester ONE devices every time you push to the server. The post-receive hook would look like this:

git push --mirror http://<address of first stb-tester ONE>/git/test-pack.git &
git push --mirror http://<address of second stb-tester ONE>/git/test-pack.git &
git push --mirror http://<address of third stb-tester ONE>/git/test-pack.git &