Getting Started

The following instructions will guide you through the setup and configuration of your Stb-tester node. If you need any help, please contact us at

Physical setup


Connect the Stb-tester HDMI node as per the above diagram.

  • The network must allow HTTPS access to the Stb-tester portal on the internet. It doesn’t need to be the same network that the set-top box is on.

  • The infrared transmitter is self-adhesive; stick it over the set-top box’s IR receiver. This is a low-power transmitter (to avoid interfering with other set-top boxes in your test lab) so it has to be close against the IR receiver. Some set-top boxes are very sensitive to the placement of the transmitter; using a torch can help to find the position of the IR receiver behind the set-top box’s plastic case.

CEC control

If you will be testing an Apple TV, Fire TV, PS3, PS4, or any other device without an infrared receiver, don’t use our USB infrared transmitter. Instead, we will have supplied a CEC adapter with a USB connector and two HDMI sockets. Put the adapter in the HDMI path between Stb-tester’s HDMI input and the device-under-test’s HDMI output, as per the diagram below.

Then, enable CEC on the device-under-test:

  • Apple TV: It’s enabled by default.

  • Fire TV: Settings > Display & Sounds > HDMI CEC Device Control.

  • PS3: System Settings > Control for HDMI.

  • PS4: Settings > System > Enable HDMI Device Link.


For detailed instructions for particular types of devices, see articles tagged Device Setup in our blog.

Web portal

To control your Stb-tester node, visit your Stb-tester portal in a web browser. The address is something like https://<company> where <company> is different for each company or team. If you don’t know the address for your Stb-tester installation, contact

Sign in

The portal uses your GitHub account to log in. (If you don’t already have a GitHub account, you can create a free account.)


The first time you log in, you will be redirected to a GitHub authorization form that asks you to grant us permission to see what Organizations and Teams your GitHub user belongs to. We use this information to determine whether you are allowed to access the Stb-tester portal; we do not have access to your private Git repositories or any other account information.


Live video

In the right-hand pane you should see the live video from your set-top box:


The live video only works if you are accessing the portal from the same local network as the Stb-tester node. If you are accessing the Stb-tester portal from a different network, you can view a low-framerate stream of JPEG screenshots by clicking the gear icon underneath the video:


You can switch between the different Stb-tester nodes in your test farm by clicking on the node name in the top left corner:



If your Stb-tester node doesn’t appear in the portal, it may not have the sufficient network access to reach the portal. See our Troubleshooting page for help.

Manual control

Click the Manual control tab to send keypresses interactively to the set-top box.


Each model of set-top box recognizes a different infrared protocol. We will see how to record your Remote control configuration below. You can also customise the remote control graphic (see Configuration Reference).

Run a test


The Stb-tester portal comes with some example testcases. Select one (or more) testcases and press Run tests.

While the test runs, you will see the status of the test in the right-hand side of the Stb-tester portal, above the live video.

This test will probably fail, because:

  • Your set-top box doesn’t understand the infrared signals that Stb-tester is sending.

  • Your set-top box doesn’t behave in the way that the testcase expects.

Don’t worry! Soon we will show you how to specify the infrared configuration for your set-top box, and how to write your own testcases.

View test results

When the test has completed, click on “Test results”, then select “master”. You will see the results of all the tests that have run before. Select a test to view a video recording, logs, and other test artifacts.


You can search through previous test runs using our flexible search filter. See the User Interface Reference for details.

Remote control configuration

Stb-tester needs to know the infrared protocol that your device-under-test understands. If you are testing a common device like a Roku, Apple TV, or XBox, we can provide a configuration file that describes the remote-control’s infrared protocol.

If the device is your own set-top box, we will need to record the infrared protocol of your remote-control for you. Please post us your remote-control unit – contact for details.

If you have a RedRat infrared receiver you can record the infrared protocol yourself following these instructions.

The test-pack git repository

The testcases (Python scripts) are stored in a git repository, along with some configuration files. This git repository is hosted on GitHub in a private repository – only users in your organization will have access.

The address of the git repository is shown in the stb-tester portal:


Follow that link to view your test scripts in GitHub’s web interface.

Testcases are Python functions

Testcases are Python functions stored in the test-pack under tests/*.py. The function name must begin with test_ (for example test_that_pressing_EPG_opens_the_guide).

In the testcase you can use the following functions:

  •"KEY_HOME") to send a key-press. You can use any of the key names specified in your infrared configuration file — just hover your mouse over the remote control in the Stb-tester portal to see each key name.

  • stbt.wait_for_match("guide-logo.png") to search for an image and fail the test if the specified image isn’t found within 10 seconds. See Reference images below for creating these reference images.

  • stbt.match("guide-logo.png") is like wait_for_match but instead of failing the test, it returns a false value if the image isn’t found. You can use this to implement more complex logic in your tests.

  • stbt.wait_for_motion(mask="channel-patch-mask.png") searches for motion and fails the test if it doesn’t detect motion within 10 seconds. You can specify an optional mask image to specify which areas of the frame to ignore.

For more details, see the stbt Python API reference.

Reference images

Press the Screenshot button underneath the live video view in the Stb-tester portal. This will take a lossless screenshot from the system-under-test as a PNG file.

From here you can drag on the image to crop it: Select the part that you want to match in your testcase, then press the Download button.


Save the screenshot into your test-pack git repository under tests/images/. The image you give to stbt.match or stbt.wait_for_match in your Python script is a relative path from the Python file itself. For example if you save the image as tests/images/roku-logo.png then you can use stbt.wait_for_match("images/roku-logo.png").