Python API Overview#

Testcases are Python functions stored in the test-pack git repository under tests/*.py. The function name must begin with test_.


import stbt

# You can import your own helper libraries from the test-pack.
import dialogues

def test_that_pressing_EPG_opens_the_guide():
    # We recommend starting each testcase with setup steps so that
    # the testcase can be run no matter what state the device-under-
    # test is in. Note that you can call other Python functions
    # defined elsewhere in your test-pack.
    if dialogues.modal_dialogue_is_up():

    # Send an infrared keypress:"KEY_EPG")

    # Verify that the device-under-test has reacted appropriately:

Controlling the system-under-test#

Remote control#

Network-based protocols#

Some devices (such as the Roku and some Smart TVs) can be controlled via HTTP or other network protocols. You can use any Python networking library to make network requests to such devices (to install third-party Python libraries see Customising the test-run environment). We recommend the Python requests library, which is already installed.

Verifying the system-under-test’s behaviour#

Searching for an image#

Use stbt.match with assert and stbt.wait_until for a more flexible alternative to stbt.wait_for_match. For example, to wait for an image to disappear:"KEY_CLOSE")
assert wait_until(lambda: not stbt.match("guide.png"))

Searching for text using OCR (optical character recognition)#

Searching for motion#

Miscellaneous video APIs#

Audio APIs#

  • stbt.get_rms_volume: Calculate the average RMS volume over a given duration.

  • stbt.wait_for_volume_change: Wait for changes in the RMS audio volume. Can detect the start of content playback or unmuting; bleeps or clicks while navigating the UI; or beeps in an A/V sync video.

  • stbt.audio_chunks: Low-level API to get raw audio samples for custom analysis.

Custom image processing#

Stb-tester can give you raw video frames for you to do your own image processing with OpenCV’s “cv2” Python API. Stb-tester’s video frames are numpy.ndarray objects, which is the same format that OpenCV uses.

To save a frame to disk, use cv2.imwrite. Note that any file you write to the current working directory will appear as an artifact in the test-run results.


  • stbt.draw_text: Write the specified text on this test-run’s video recording.

Anything you write to stdout or stderr appears in the test-run’s logfile in stb-tester’s test-results viewer.


For some customers we run Prometheus and Grafana on your Stb-tester Portal. (Prometheus is an open-source time-series database for metrics; Grafana is an open-source dashboard & reporting tool driven by the data in Prometheus.) If this is enabled on your Portal, you can log metrics to Prometheus using the following APIs:



If your testcase raises one of the following exceptions, it is considered a test failure:

Any other exception is considered a test error. For some examples see Investigating intermittent bugs.