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 firstname.lastname@example.org.
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.
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.
To control your Stb-tester node, visit your Stb-tester portal in a web
browser. The address is something like
where <company> is different for each company or team. If you don’t know
the address for your Stb-tester installation, contact email@example.com.
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.
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.
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 firstname.lastname@example.org for details.
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
The function name must begin with
test_ (for example
In the testcase you can use the following functions:
stbt.press("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.
wait_for_matchbut 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
maskimage to specify which areas of the frame to ignore.
For more details, see the stbt Python API reference.
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
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