stbt Python API¶

Searching for an image¶

• wait_for_match: Search for the specified image in the video stream; raise MatchTimeout if not found within a certain timeout.
• match: Search for the specified image in a single video frame; return a truthy/falsey MatchResult.
• match_all: Search for all instances of the specified image in a single video frame.

Use match with assert and wait_until for a more flexible alternative to wait_for_match. For example, to wait for an image to disappear:

stbt.press("KEY_CLOSE")
assert wait_until(lambda: not stbt.match("guide.png"))

Searching for text using OCR (optical character recognition)¶

• match_text: Search for the specified text in a single video frame; return a truthy/falsey TextMatchResult.
• ocr: Read the text present in a video frame.

Searching for motion¶

• wait_for_motion: Search for motion in the video stream; raise MotionTimeout if no motion is found within a certain timeout.
• detect_motion: Generator that yields a sequence of one MotionResult for each frame processed from the system-under-test, indicating whether any motion was detected.

Miscellaneous¶

• is_screen_black: Check for the presence of a black screen in a single video frame.

stbt.as_precondition¶

stbt.as_precondition(message)¶

Context manager that replaces test failures with test errors.

Stb-tester’s reports show test failures (that is, UITestFailure or AssertionError exceptions) as red results, and test errors (that is, unhandled exceptions of any other type) as yellow results. Note that wait_for_match, wait_for_motion, and similar functions raise a UITestFailure when they detect a failure. By running such functions inside an as_precondition context, any UITestFailure or AssertionError exceptions they raise will be caught, and a PreconditionError will be raised instead.

When running a single testcase hundreds or thousands of times to reproduce an intermittent defect, it is helpful to mark unrelated failures as test errors (yellow) rather than test failures (red), so that you can focus on diagnosing the failures that are most likely to be the particular defect you are looking for. For more details see Test failures vs. errors.

Parameters:	message (str) – A description of the precondition. Word this positively: “Channels tuned”, not “Failed to tune channels”.
Raises:	PreconditionError if the wrapped code block raises a UITestFailure or AssertionError.

Example:

def test_that_the_on_screen_id_is_shown_after_booting():
    channel = 100

    with stbt.as_precondition("Tuned to channel %s" % channel):
        mainmenu.close_any_open_menu()
        channels.goto_channel(channel)
        power.cold_reboot()
        assert channels.is_on_channel(channel)

    stbt.wait_for_match("on-screen-id.png")

stbt.ConfigurationError¶

exception stbt.ConfigurationError¶

Bases: exceptions.Exception

An error with your stbt configuration file.

stbt.crop¶

stbt.crop(frame, region)¶

Returns an image containing the specified region of frame.

Parameters:	frame (stbt.Frame or numpy.ndarray) – An image in OpenCV format (for example as returned by frames, get_frame and load_image, or the frame parameter of MatchResult).
Returns:	An OpenCV image (numpy.ndarray) containing the specified region of the source frame. This is a view onto the original data, so if you want to modify the cropped image call its copy() method first.

stbt.detect_motion¶

stbt.detect_motion(timeout_secs=10, noise_threshold=None, mask=None, region=Region.ALL)¶

Generator that yields a sequence of one MotionResult for each frame processed from the device-under-test’s video stream.

The MotionResult indicates whether any motion was detected – that is, any difference between two consecutive frames.

Parameters:

timeout_secs (int or float or None) – A timeout in seconds. After this timeout the iterator will be exhausted. Thas is, a for loop like for m in detect_motion(timeout_secs=10) will terminate after 10 seconds. If timeout_secs is None then the iterator will yield frames forever. Note that you can stop iterating (for example with break) at any time. noise_threshold (float) – The amount of noise to ignore. This is only useful with noisy analogue video sources. Valid values range from 0 (all differences are considered noise; a value of 0 will never report motion) to 1.0 (any difference is considered motion). This defaults to 0.84. You can override the global default value by setting noise_threshold in the [motion] section of .stbt.conf. mask (str or numpy.ndarray) – A black & white image that specifies which part of the image to search for motion. White pixels select the area to analyse; black pixels select the area to ignore. The mask must be the same size as the video frame. This can be a string (a filename that will be resolved as per load_image) or a single-channel image in OpenCV format. region (Region) – Only analyze the specified region of the video frame. If you specify both region and mask, the mask must be the same size as the region.

Added in v28: The region parameter.

stbt.draw_text¶

stbt.draw_text(text, duration_secs=3)¶

Write the specified text to the output video.

Parameters:	text (str) – The text to write. duration_secs (int or float) – The number of seconds to display the text.

stbt.Frame¶

class stbt.Frame¶

A frame of video.

A Frame is what you get from stbt.get_frame and stbt.frames. It is a subclass of numpy.ndarray, which is the type that OpenCV uses to represent images. Data is stored in 8-bit, 3 channel BGR format.

In addition to the members inherited from numpy.ndarray, Frame defines the following attributes:

• time (float) - the wall-clock time that this video-frame was captured as number of seconds since the unix epoch (1970-01-01T00:00:00Z). This is the same format used by the Python standard library function time.time.

Frame was added in stb-tester v26.

stbt.FrameObject¶

class stbt.FrameObject(frame=None)¶

Base class for user-defined Frame Objects.

The Frame Object pattern is used to simplify testcase development and maintenance. Frame Objects are a layer of abstraction between your testcases and the stbt image processing APIs. They are easy to write and cheap to maintain.

A Frame Object extracts information from a frame of video, typically by calling stbt.ocr or stbt.match. All of your testcases use these objects rather than using ocr or match directly. A Frame Object translates from the vocabulary of low-level image processing functions and regions (like stbt.ocr(region=stbt.Region(213, 23, 200, 36))) to the vocabulary of high-level features and user-facing concepts (like programme_title).

FrameObject is a base class that makes it easier to create well-behaved Frame Objects. Your own Frame Object classes should:

1. Derive from FrameObject.
2. Define an is_visible property that returns True or False.
3. Define any other properties for information that you want to extract from the frame.
4. Take care to pass self._frame into any image processing function you call.

A Frame Object instance is considered “truthy” if it is visible. Any other properties (apart from is_visible) will return None if the object isn’t visible.

Frame Objects are immutable, because they represent information about a specific frame of video. If you define any methods that change the state of the device-under-test, they should return a new Frame Object instead of modifying self.

Each property will be cached the first time is is referenced. This allows writing test cases in a natural way while expensive operations like ocr will only be done once per frame.

The FrameObject base class defines the following methods:

• __init__ – The default constructor takes an optional frame; if the frame is not provided, it will grab a frame from the device-under-test.
• __nonzero__ – Delegates to is_visible. The object will only be considered True if it is visible.
• __repr__ – The object’s string representation includes all the user-defined public properties.
• __hash__ and __cmp__ – Two instances of the same FrameObject type are considered equal if the values of all the public properties match, even if the underlying frame is different.

For more background information on Frame Objects see Improve black-box testing agility: meet the Frame Object pattern.

Example

We’ll create a Frame Object class for the dialog box we see in this image that we’ve captured from our (hypothetical) set-top box:

Here’s our Frame Object class:

>>> class Dialog(FrameObject):
...     @property
...     def is_visible(self):
...         return bool(self._info)
...
...     @property
...     def title(self):
...         return ocr(region=Region(396, 249, 500, 50), frame=self._frame)
...
...     @property
...     def message(self):
...         right_of_info = Region(
...             x=self._info.region.right, y=self._info.region.y,
...             width=390, height=self._info.region.height)
...         return ocr(region=right_of_info, frame=self._frame) \
...                .replace('\n', ' ')
...
...     @property
...     def _info(self):
...         return match('../tests/info.png', frame=self._frame)

Let’s take this line by line:

class Dialog(FrameObject):

We create a class deriving from the FrameObject base class.

@property
def is_visible(self):
    return bool(self._info)

All Frame Objects must define the is_visible property, which will determine the truthiness of the object. Returning True from this property indicates that this Frame Object class can be used with the provided frame and that the values of the other properties are likely to be valid.

In this example we only return True if we see the “info” icon that appears on each dialog box. The actual work is delegated to the private property _info defined below.

It’s a good idea to return simple types from these properties rather than a MatchResult, to make the __repr__ cleaner and to preserve equality properties.

@property
def title(self):
    return ocr(region=Region(396, 249, 500, 50), frame=self._frame)

The base class provides a self._frame member. Here we’re using stbt.ocr to extract the dialog’s title text from this frame. This is the basic form that many Frame Object properties will take.

This property demonstrates an advantage of Frame Objects. Your testcases now look like this:

assert Dialog().title == "Information"

instead of this:

assert stbt.ocr(region=stbt.Region(396, 249, 500, 50)) == "Information"

This is clearer because it reveals the intention of the testcase author (we’re looking for the word in the title of the dialog). It is also easier (cheaper) to maintain: If the position of the title moves, you only need to update the implementation of Dialog.title; you won’t need to change any of your testcases.

When defining Frame Objects you must take care to pass self._frame into every call to an image processing function (like our title property does when it calls ocr, above). Otherwise the return values won’t correspond to the frame you were expecting.

@property
def message(self):
    right_of_info = Region(
        x=self._info.region.right, y=self._info.region.y,
        width=390, height=self._info.region.height)
    return ocr(region=right_of_info, frame=self._frame) \
           .replace('\n', ' ')

This property demonstrates an advantage of Frame Objects over stand-alone helper functions. We are using the position of the “info” icon to find this message. Because the private _info property is shared between this property and is_visible we don’t need to compute it twice – the FrameObject base class will remember the value from the first time it was computed.

@property
def _info(self):
    return match('../tests/info.png', frame=self._frame)

This is a private property because its name starts with _. It will not appear in __repr__ nor count toward equality comparisons, but the result from it will still be cached. This is useful for sharing intermediate values between your public properties, particularly if they are expensive to calculate. In this example we use _info from is_visible and message.

You wouldn’t want this to be a public property because it returns a MatchResult which includes the entire frame passed into match.

Using our new Frame Object class

The default constructor will grab a frame from the device-under-test. This allows you to use Frame Objects with wait_until like this:

dialog = wait_until(Dialog)
assert 'great' in dialog.message

We can also explicitly pass in a frame. This is mainly useful for unit-testing your Frame Objects.

The examples below will use these example frames:

dialog	no_dialog
dialog_bunnies	no_dialog_bunnies
dialog_fab

Some basic operations:

>>> print dialog.message
This set-top box is great
>>> print dialog_fab.message
This set-top box is fabulous

FrameObject defines truthiness of your objects based on the mandatory is_visible property:

>>> bool(dialog)
True
>>> bool(no_dialog)
False

If is_visible is falsey, all the rest of the properties will be None:

>>> print no_dialog.message
None

This enables usage like:

assert wait_until(lambda: Dialog().title == 'Information')

FrameObject defines __repr__ so that you don’t have to. It looks like this:

>>> dialog
Dialog(is_visible=True, message=u'This set-top box is great', title=u'Information')
>>> dialog_fab
Dialog(is_visible=True, message=u'This set-top box is fabulous', title=u'Information')
>>> no_dialog
Dialog(is_visible=False)

This makes it convenient to use doctests for unit-testing your Frame Objects.

Frame Objects with identical property values are equal, even if the backing frames are not:

>>> assert dialog == dialog
>>> assert dialog == dialog_bunnies
>>> assert dialog != dialog_fab
>>> assert dialog != no_dialog

This can be useful for detecting changes in the UI (while ignoring live TV in the background) or waiting for the UI to stop changing before interrogating it.

All falsey Frame Objects of the same type are equal:

>>> assert no_dialog == no_dialog
>>> assert no_dialog == no_dialog_bunnies

FrameObject defines __hash__ too so you can store them in a set or in a dict:

>>> {dialog}
set([Dialog(is_visible=True, message=u'This set-top box is great', title=u'Information')])
>>> len({no_dialog, dialog, dialog, dialog_bunnies})
2

stbt.frames¶

stbt.frames(timeout_secs=None)¶

Generator that yields video frames captured from the device-under-test.

Parameters:	timeout_secs (int or float or None) – A timeout in seconds. After this timeout the iterator will be exhausted. That is, a for loop like for f, t in frames(timeout_secs=10) will terminate after 10 seconds. If timeout_secs is None (the default) then the iterator will yield frames forever. Note that you can stop iterating (for example with break) at any time.
Returns:	A (frame, timestamp) tuple for each video frame: frame is a stbt.Frame (that is, an OpenCV image). timestamp (int): DEPRECATED. Timestamp in nanoseconds. Use frame.time instead.

stbt.get_config¶

stbt.get_config(section, key, default=None, type_=str)¶

Read the value of key from section of the test-pack configuration file.

For example, if your configuration file looks like this:

[test_pack]
stbt_version = 28

[my_company_name]
stb_ip = 192.168.1.23

then you can read the value from your test script like this:

stb_ip = stbt.get_config("my_company_name", "stb_ip")

This searches in the .stbt.conf file at the root of your test-pack, and in the config/test-farm/<hostname>.conf file matching the hostname of the stb-tester device where the script is running. Values in the host-specific config file override values in .stbt.conf. See Configuration files for more details.

Raises ConfigurationError if the specified section or key is not found, unless default is specified (in which case default is returned).

stbt.get_frame¶

stbt.get_frame()¶

Grabs a video frame captured from the device-under-test.

Returns:	The latest video frame in OpenCV format (a stbt.Frame).

stbt.is_screen_black¶

stbt.is_screen_black(frame=None, mask=None, threshold=None, region=Region.ALL)¶

Check for the presence of a black screen in a video frame.

Parameters:

frame (stbt.Frame or numpy.ndarray) – If this is specified it is used as the video frame to check; otherwise a new frame is grabbed from the device-under-test. This is an image in OpenCV format (for example as returned by frames and get_frame). mask (str or numpy.ndarray) – A black & white image that specifies which part of the image to analyse. White pixels select the area to analyse; black pixels select the area to ignore. The mask must be the same size as the video frame. This can be a string (a filename that will be resolved as per load_image) or a single-channel image in OpenCV format. threshold (int) – Even when a video frame appears to be black, the intensity of its pixels is not always 0. To differentiate almost-black from non-black pixels, a binary threshold is applied to the frame. The threshold value is in the range 0 (black) to 255 (white). The global default can be changed by setting threshold in the [is_screen_black] section of .stbt.conf. region (Region) – Only analyze the specified region of the video frame. If you specify both region and mask, the mask must be the same size as the region.

Returns:

True or False.

Added in v28: The region parameter.

stbt.load_image¶

stbt.load_image(filename, flags=cv2.IMREAD_COLOR)¶

Find & read an image from disk.

If given a relative filename, this will search in the directory of the Python file that called load_image, then in the directory of that file’s caller, etc. This allows you to use load_image in a helper function, and then call that helper function from a different Python file passing in a filename relative to the caller.

Finally this will search in the current working directory. This allows loading an image that you had previously saved to disk during the same test run.

This is the same lookup algorithm used by stbt.match and similar functions.

Parameters:	filename (str or unicode) – A relative or absolute filename. flags – Flags to pass to cv2.imread.
Returns:	An image in OpenCV format (a numpy.ndarray of 8-bit values, 3 channel BGR).
Raises:	IOError if the specified path doesn’t exist or isn’t a valid image file.

Added in v28.

stbt.match¶

stbt.match(image, frame=None, match_parameters=None, region=Region.ALL)¶

Search for an image in a single video frame.

Parameters:

image (string or numpy.ndarray) – The image to search for. It can be the filename of a png file on disk, or a numpy array containing the pixel data in 8-bit BGR format. Filenames should be relative paths. See stbt.load_image for the path lookup algorithm. 8-bit BGR numpy arrays are the same format that OpenCV uses for images. This allows generating templates on the fly (possibly using OpenCV) or searching for images captured from the device-under-test earlier in the test script. frame (stbt.Frame or numpy.ndarray) – If this is specified it is used as the video frame to search in; otherwise a new frame is grabbed from the device-under-test. This is an image in OpenCV format (for example as returned by frames and get_frame). match_parameters (MatchParameters) – Customise the image matching algorithm. See MatchParameters for details. region (Region) – Only search within the specified region of the video frame.

Returns:

A MatchResult, which will evaluate to true if a match was found, false otherwise.

stbt.match_all¶

stbt.match_all(image, frame=None, match_parameters=None, region=Region.ALL)¶

Search for all instances of an image in a single video frame.

Arguments are the same as match.

Returns:	An iterator of zero or more MatchResult objects (one for each position in the frame where image matches).

Examples:

all_buttons = list(stbt.match_all("button.png"))

for match_result in stbt.match_all("button.png"):
    # do something with match_result here
    ...

stbt.match_text¶

stbt.match_text(text, frame=None, region=Region.ALL, mode=OcrMode.PAGE_SEGMENTATION_WITHOUT_OSD, lang=None, tesseract_config=None, case_sensitive=False, upsample=True, text_color=None)¶

Search for the specified text in a single video frame.

This can be used as an alternative to match, searching for text instead of an image.

Parameters:	text (unicode) – The text to search for. frame – See ocr. region – See ocr. mode – See ocr. lang – See ocr. tesseract_config – See ocr. upsample – See ocr. text_color – See ocr. case_sensitive (bool) – Ignore case if False (the default).
Returns:	A TextMatchResult, which will evaluate to True if the text was found, false otherwise.

For example, to select a button in a vertical menu by name (in this case “TV Guide”):

m = stbt.match_text("TV Guide")
assert m.match
while not stbt.match('selected-button.png').region.contains(m.region):
    stbt.press('KEY_DOWN')

Added in v28: The upsample and text_color parameters.

stbt.MatchParameters¶

class stbt.MatchParameters(match_method=None, match_threshold=None, confirm_method=None, confirm_threshold=None, erode_passes=None)¶

Parameters to customise the image processing algorithm used by match, wait_for_match, and press_until_match.

You can change the default values for these parameters by setting a key (with the same name as the corresponding python parameter) in the [match] section of .stbt.conf. But we strongly recommend that you don’t change the default values from what is documented here.

You should only need to change these parameters when you’re trying to match a template image that isn’t actually a perfect match – for example if there’s a translucent background with live TV visible behind it; or if you have a template image of a button’s background and you want it to match even if the text on the button doesn’t match.

Parameters:

match_method (str) – The method to be used by the first pass of stb-tester’s image matching algorithm, to find the most likely location of the “template” image within the larger source image. Allowed values are “sqdiff-normed”, “ccorr-normed”, and “ccoeff-normed”. For the meaning of these parameters, see OpenCV’s cv2.matchTemplate. We recommend that you don’t change this from its default value of “sqdiff-normed”. match_threshold (float) – How strong a result from the first pass must be, to be considered a match. Valid values range from 0 (anything is considered to match) to 1 (the match has to be pixel perfect). This defaults to 0.8. confirm_method (str) – The method to be used by the second pass of stb-tester’s image matching algorithm, to confirm that the region identified by the first pass is a good match. The first pass often gives false positives (it reports a “match” for an image that shouldn’t match). The second pass is more CPU-intensive, but it only checks the position of the image that the first pass identified. The allowed values are: ”none”: Do not confirm the match. Assume that the potential match found is correct. ”absdiff”: Compare the absolute difference of each pixel from the template image against its counterpart from the candidate region in the source video frame. ”normed-absdiff”:   Normalise the pixel values from both the template image and the candidate region in the source video frame, then compare the absolute difference as with “absdiff”. This gives better results with low-contrast images. We recommend setting this as the default confirm_method in stbt.conf, with a confirm_threshold of 0.30. confirm_threshold (float) – The maximum allowed difference between any given pixel from the template image and its counterpart from the candidate region in the source video frame, as a fraction of the pixel’s total luminance range. Valid values range from 0 (more strict) to 1.0 (less strict). Useful values tend to be around 0.16 for the “absdiff” method, and 0.30 for the “normed-absdiff” method. erode_passes (int) – After the “absdiff” or “normed-absdiff” absolute difference is taken, stb-tester runs an erosion algorithm that removes single-pixel differences to account for noise. Useful values are 1 (the default) and 0 (to disable this step).

stbt.MatchResult¶

class stbt.MatchResult¶

The result from match.

Variables:

time (float) – The time at which the video-frame was captured, in seconds since 1970-01-01T00:00Z. This timestamp can be compared with system time (time.time()). match (bool) – True if a match was found. This is the same as evaluating MatchResult as a bool. That is, if result: will behave the same as if result.match:. region (Region) – Coordinates where the image was found (or of the nearest match, if no match was found). first_pass_result (float) – Value between 0 (poor) and 1.0 (excellent match) from the first pass of stb-tester’s image matching algorithm (see MatchParameters for details). frame (Frame) – The video frame that was searched, as given to match. image – The reference image that was searched for, as given to match. timestamp (int) – DEPRECATED. Timestamp in nanoseconds. Use time instead.

stbt.MatchTimeout¶

exception stbt.MatchTimeout¶

Bases: _stbt.core.UITestFailure

Exception raised by wait_for_match.

Variables:	screenshot (Frame) – The last video frame that wait_for_match checked before timing out. expected (str) – Filename of the image that was being searched for. timeout_secs (int or float) – Number of seconds that the image was searched for.

stbt.MotionResult¶

class stbt.MotionResult¶

The result from detect_motion and wait_for_motion.

Variables:

time (float) – The time at which the video-frame was captured, in seconds since 1970-01-01T00:00Z. This timestamp can be compared with system time (time.time()). motion (bool) – True if motion was found. This is the same as evaluating MotionResult as a bool. That is, if result: will behave the same as if result.motion:. region (Region) – Bounding box where the motion was found, or None if no motion was found. frame (Frame) – The video frame in which motion was (or wasn’t) found. timestamp (int) – DEPRECATED. Timestamp in nanoseconds. Use time instead.

Added in v28: The frame attribute.

stbt.MotionTimeout¶

exception stbt.MotionTimeout¶

Bases: _stbt.core.UITestFailure

Exception raised by wait_for_motion.

Variables:	screenshot (Frame) – The last video frame that wait_for_motion checked before timing out. mask (str or None) – Filename of the mask that was used, if any. timeout_secs (int or float) – Number of seconds that motion was searched for.

stbt.ocr¶

stbt.ocr(frame=None, region=Region.ALL, mode=OcrMode.PAGE_SEGMENTATION_WITHOUT_OSD, lang=None, tesseract_config=None, tesseract_user_words=None, tesseract_user_patterns=None, upsample=True, text_color=None)¶

Return the text present in the video frame as a Unicode string.

Perform OCR (Optical Character Recognition) using the “Tesseract” open-source OCR engine.

Parameters:

frame – If this is specified it is used as the video frame to process; otherwise a new frame is grabbed from the device-under-test. This is an image in OpenCV format (for example as returned by frames and get_frame). region (Region) – Only search within the specified region of the video frame. mode (OcrMode) – Tesseract’s layout analysis mode. lang (str) – The three-letter ISO-639-3 language code of the language you are attempting to read; for example “eng” for English or “deu” for German. More than one language can be specified by joining with ‘+’; for example “eng+deu” means that the text to be read may be in a mixture of English and German. This defaults to “eng” (English). You can override the global default value by setting lang in the [ocr] section of .stbt.conf. You may need to install the tesseract language pack; see installation instructions here. tesseract_config (dict) – Allows passing configuration down to the underlying OCR engine. See the tesseract documentation for details. tesseract_user_words (unicode string, or list of unicode strings) – List of words to be added to the tesseract dictionary. To replace the tesseract system dictionary altogether, also set tesseract_config={'load_system_dawg': False, 'load_freq_dawg': False}. tesseract_user_patterns (unicode string, or list of unicode strings) – List of patterns to add to the tesseract dictionary. The tesseract pattern language corresponds roughly to the following regular expressions: tesseract regex ========= =========== \c [a-zA-Z] \d [0-9] \n [a-zA-Z0-9] \p [:punct:] \a [a-z] \A [A-Z] \* * upsample (bool) – Upsample the image 3x before passing it to tesseract. This helps to preserve information in the text’s anti-aliasing that would otherwise be lost when tesseract binarises the image. This defaults to True; you should only disable it if you are doing your own pre-processing on the image. text_color (3-element tuple of integers between 0 and 255, BGR order.) – Color of the text. Specifying this can improve OCR results when tesseract’s default thresholding algorithm doesn’t detect the text, for example white text on a light-colored background or text on a translucent overlay.

Added in v28: Parameters upsample (to disable stb-tester’s pre-processing of the image) and text_color.

stbt.OcrMode¶

class stbt.OcrMode¶

Options to control layout analysis and assume a certain form of image.

For a (brief) description of each option, see the tesseract(1) man page.

ORIENTATION_AND_SCRIPT_DETECTION_ONLY = 0¶

PAGE_SEGMENTATION_WITH_OSD = 1¶

PAGE_SEGMENTATION_WITHOUT_OSD_OR_OCR = 2¶

PAGE_SEGMENTATION_WITHOUT_OSD = 3¶

SINGLE_COLUMN_OF_TEXT_OF_VARIABLE_SIZES = 4¶

SINGLE_UNIFORM_BLOCK_OF_VERTICALLY_ALIGNED_TEXT = 5¶

SINGLE_UNIFORM_BLOCK_OF_TEXT = 6¶

SINGLE_LINE = 7¶

SINGLE_WORD = 8¶

SINGLE_WORD_IN_A_CIRCLE = 9¶

SINGLE_CHARACTER = 10¶

stbt.PreconditionError¶

exception stbt.PreconditionError¶

Exception raised by as_precondition.

stbt.press¶

stbt.press(key, interpress_delay_secs=None)¶

Send the specified key-press to the device under test.

Parameters:

key (str) – The name of the key/button. If you are using infrared control, this is a key name from your lircd.conf configuration file. If you are using HDMI CEC control, see the available key names here. Note that some devices might not understand all of the CEC commands in that list. interpress_delay_secs (int or float) – The minimum time to wait after a previous key-press, in order to accommodate the responsiveness of the device-under-test. This defaults to 0.3. You can override the global default value by setting interpress_delay_secs in the [press] section of .stbt.conf.

stbt.press_until_match¶

stbt.press_until_match(key, image, interval_secs=None, max_presses=None, match_parameters=None, region=Region.ALL)¶

Call press as many times as necessary to find the specified image.

Parameters:	key – See press. image – See match. interval_secs (int or float) – The number of seconds to wait for a match before pressing again. Defaults to 3. You can override the global default value by setting interval_secs in the [press_until_match] section of .stbt.conf. max_presses (int) – The number of times to try pressing the key and looking for the image before giving up and raising MatchTimeout. Defaults to 10. You can override the global default value by setting max_presses in the [press_until_match] section of .stbt.conf. match_parameters – See match. region – See match.
Returns:	MatchResult when the image is found.
Raises:	MatchTimeout if no match is found after timeout_secs seconds.

Added in v28: The region parameter.

stbt.Region¶

class stbt.Region¶

Region(x, y, width=width, height=height) or Region(x, y, right=right, bottom=bottom)

Rectangular region within the video frame.

For example, given the following regions a, b, and c:

- 01234567890123
0 ░░░░░░░░
1 ░a░░░░░░
2 ░░░░░░░░
3 ░░░░░░░░
4 ░░░░▓▓▓▓░░▓c▓
5 ░░░░▓▓▓▓░░▓▓▓
6 ░░░░▓▓▓▓░░░░░
7 ░░░░▓▓▓▓░░░░░
8     ░░░░░░b░░
9     ░░░░░░░░░

>>> a = Region(0, 0, width=8, height=8)
>>> b = Region(4, 4, right=13, bottom=10)
>>> c = Region(10, 4, width=3, height=2)
>>> a.right
8
>>> b.bottom
10
>>> b.contains(c), a.contains(b), c.contains(b)
(True, False, False)
>>> b.extend(x=6, bottom=-4) == c
True
>>> a.extend(right=5).contains(c)
True
>>> a.width, a.extend(x=3).width, a.extend(right=-3).width
(8, 5, 5)
>>> c.replace(bottom=10)
Region(x=10, y=4, right=13, bottom=10)
>>> Region.intersect(a, b)
Region(x=4, y=4, right=8, bottom=8)
>>> Region.intersect(a, b) == Region.intersect(b, a)
True
>>> Region.intersect(c, b) == c
True
>>> print Region.intersect(a, c)
None
>>> print Region.intersect(None, a)
None
>>> quadrant = Region(x=float("-inf"), y=float("-inf"), right=0, bottom=0)
>>> quadrant.translate(2, 2)
Region(x=-inf, y=-inf, right=2, bottom=2)
>>> c.translate(x=-9, y=-3)
Region(x=1, y=1, right=4, bottom=3)
>>> Region.intersect(Region.ALL, c) == c
True
>>> Region.ALL
Region.ALL
>>> print Region.ALL
Region.ALL
>>> c.above()
Region(x=10, y=-inf, right=13, bottom=4)
>>> c.below()
Region(x=10, y=6, right=13, bottom=inf)
>>> a.right_of()
Region(x=8, y=0, right=inf, bottom=8)
>>> a.right_of(width=2)
Region(x=8, y=0, right=10, bottom=8)
>>> c.left_of()
Region(x=-inf, y=4, right=10, bottom=6)

x¶

The x coordinate of the left edge of the region, measured in pixels from the left of the video frame (inclusive).

y¶

The y coordinate of the top edge of the region, measured in pixels from the top of the video frame (inclusive).

right¶

The x coordinate of the right edge of the region, measured in pixels from the left of the video frame (exclusive).

bottom¶

The y coordinate of the bottom edge of the region, measured in pixels from the top of the video frame (exclusive).

x, y, right, and bottom can be infinite – that is, float("inf") or -float("inf").

width¶

The width of the region, measured in pixels.

height¶

The height of the region, measured in pixels.

static intersect(a, b)¶

Returns:	The intersection of regions a and b, or None if the regions don’t intersect.

Either a or b can be None so intersect is commutative and associative.

contains(other)¶

Returns:	True if other is entirely contained within self.

extend(x=0, y=0, right=0, bottom=0)¶

Returns:	A new region with the edges of the region adjusted by the given amounts.

replace(x=None, y=None, width=None, height=None, right=None, bottom=None)¶

Returns:	A new region with the edges of the region set to the given coordinates.

This is similar to extend, but it takes absolute coordinates within the image instead of adjusting by a relative number of pixels.

translate(x=0, y=0)¶

Returns:	A new region with the position of the region adjusted by the given amounts.

above(height=inf)¶

Returns:	A new region above the current region, extending to the top of the frame (or to the specified height).

below(height=inf)¶

Returns:	A new region below the current region, extending to the bottom of the frame (or to the specified height).

right_of(width=inf)¶

Returns:	A new region to the right of the current region, extending to the right edge of the frame (or to the specified width).

left_of(width=inf)¶

Returns:	A new region to the left of the current region, extending to the left edge of the frame (or to the specified width).

stbt.TextMatchResult¶

class stbt.TextMatchResult¶

The result from match_text.

Variables:

time (float) – The time at which the video-frame was captured, in seconds since 1970-01-01T00:00Z. This timestamp can be compared with system time (time.time()). match (bool) – True if a match was found. This is the same as evaluating MatchResult as a bool. That is, if result: will behave the same as if result.match:. region (Region) – Bounding box where the text was found, or None if the text wasn’t found. frame (Frame) – The video frame that was searched, as given to match_text. text (unicode) – The text that was searched for, as given to match_text. timestamp (int) – DEPRECATED. Timestamp in nanoseconds. Use time instead.

stbt.UITestFailure¶

exception stbt.UITestFailure¶

Bases: exceptions.Exception

The test failed because the device under test didn’t behave as expected.

Inherit from this if you need to define your own test-failure exceptions.

stbt.wait_for_match¶

stbt.wait_for_match(image, timeout_secs=10, consecutive_matches=1, match_parameters=None, region=Region.ALL)¶

Search for an image in the device-under-test’s video stream.

Parameters:	image – The image to search for. See match. timeout_secs (int or float or None) – A timeout in seconds. This function will raise MatchTimeout if no match is found within this time. consecutive_matches (int) – Forces this function to wait for several consecutive frames with a match found at the same x,y position. Increase consecutive_matches to avoid false positives due to noise, or to wait for a moving selection to stop moving. match_parameters – See match. region – See match.
Returns:	MatchResult when the image is found.
Raises:	MatchTimeout if no match is found after timeout_secs seconds.

stbt.wait_for_motion¶

stbt.wait_for_motion(timeout_secs=10, consecutive_frames=None, noise_threshold=None, mask=None, region=Region.ALL)¶

Search for motion in the device-under-test’s video stream.

“Motion” is difference in pixel values between two consecutive frames.

Parameters:	timeout_secs (int or float or None) – A timeout in seconds. This function will raise MotionTimeout if no motion is detected within this time. consecutive_frames (int or str) – Considers the video stream to have motion if there were differences between the specified number of consecutive frames. This can be: a positive integer value, or a string in the form “x/y”, where “x” is the number of frames with motion detected out of a sliding window of “y” frames. This defaults to “10/20”. You can override the global default value by setting consecutive_frames in the [motion] section of .stbt.conf. noise_threshold (float) – See detect_motion. mask – See detect_motion. region – See detect_motion.
Returns:	MotionResult when motion is detected. The MotionResult’s time and frame attributes correspond to the first frame in which motion was detected.
Raises:	MotionTimeout if no motion is detected after timeout_secs seconds.

Added in v28: The region parameter.

stbt.wait_until¶

stbt.wait_until(callable_, timeout_secs=10, interval_secs=0, predicate=None, stable_secs=0)¶

Wait until a condition becomes true, or until a timeout.

Calls callable_ repeatedly (with a delay of interval_secs seconds between successive calls) until it succeeds (that is, it returns a truthy value) or until timeout_secs seconds have passed.

Parameters:

callable – any Python callable (such as a function or a lambda expression) with no arguments. timeout_secs (int or float, in seconds) – After this timeout elapses, wait_until will return the last value that callable_ returned, even if it’s falsey. interval_secs (int or float, in seconds) – Delay between successive invocations of callable_. predicate – A function that takes a single value. It will be given the return value from callable_. The return value of this function will then be used to determine truthiness. If the predicate test succeeds, wait_until will still return the original value from callable_, not the predicate value. stable_secs (int or float, in seconds) – Wait for callable_’s return value to remain the same (as determined by ==) for this duration before returning. If predicate is also given, the values returned from predicate will be compared.

Returns:

The return value from callable_ (which will be truthy if it succeeded, or falsey if wait_until timed out). If the value was truthy when the timeout was reached but it failed the predicate or stable_secs conditions (if any) then wait_until returns None.

After you send a remote-control signal to the device-under-test it usually takes a few frames to react, so a test script like this would probably fail:

press("KEY_EPG")
assert match("guide.png")

Instead, use this:

press("KEY_EPG")
assert wait_until(lambda: match("guide.png"))

Note that instead of the above assert wait_until(...) you could use wait_for_match("guide.png"). wait_until is a generic solution that also works with stbt’s other functions, like match_text and is_screen_black.

wait_until allows composing more complex conditions, such as:

# Wait until something disappears:
assert wait_until(lambda: not match("xyz.png"))

# Assert that something doesn't appear within 10 seconds:
assert not wait_until(lambda: match("xyz.png"))

# Assert that two images are present at the same time:
assert wait_until(lambda: match("a.png") and match("b.png"))

# Wait but don't raise an exception:
if not wait_until(lambda: match("xyz.png")):
    do_something_else()

# Wait for a menu selection to change. Here ``Menu`` is a `FrameObject`
# with a property called `selection` that returns a string with the
# name of the currently-selected menu item:
# The return value (``menu``) is an instance of ``Menu``.
menu = wait_until(Menu, predicate=lambda x: x.selection == "Home")

# Wait for a match to stabilise position, returning the first stable
# match. Used in performance measurements, for example to wait for a
# selection highlight to finish moving:
press("KEY_DOWN")
start_time = time.time()
match_result = wait_until(lambda: stbt.match("selection.png"),
                          predicate=lambda x: x and x.region,
                          stable_secs=2)
assert match_result
end_time = match_result.time  # this is the first stable frame
print "Transition took %s seconds" % (end_time - start_time)

Added in v28: The predicate and stable_secs parameters.

v28¶

6 February 2018.

Breaking changes:

• Passing region=None to stbt.ocr raises a TypeError instead of printing a deprecation warning. Use region=stbt.Region.ALL instead.

• Passing type_=bool to stbt.get_config now returns False for values of “0”, “false”, “off”, and “no” (ignoring case). Previously it would always return True for any non-empty value.

• stbt.get_frame and stbt.frames now return read-only frames for better performance. Use frame.copy() to get a writeable copy of the frame.

• stbt.get_frame is no longer guaranteed to return a new frame; it may return the same frame that the previous call to stbt.get_frame() returned. This may have subtle effects on the timing of existing test-scripts. Functions that depend on this behaviour should be refactored to use the stbt.frames iterator function instead.

  The benefit is that you can now call stbt.get_frame() from multiple threads. Also, code like wait_until(lambda: match('a.png') or match('b.png')) can run faster as the second match will no longer block waiting for a new frame.

  If this change causes you problems, you can add the following to your .stbt.conf file to restore the old behaviour:

  [global]
  use_old_threading_behaviour = true
  

New features:

• Multithreading support: stbt functions like wait_for_match can now be used from multiple threads simultaneously. Each call to stbt.frames returns an independent iterator that can be used concurrently.
• New function stbt.crop to crop a region from a video-frame.
• New function stbt.load_image to load an image from disk, using the same path lookup algorithm used by wait_for_match and friends.
• ocr and match_text have a new parameter text_color. Specifying this can improve OCR results when tesseract’s default thresholding algorithm doesn’t detect the text, for example for light-colored text or text on a translucent overlay.
• The pre-processing performed by ocr and match_text can now be disabled by passing upscale=False. This is useful if you want to do your own pre-processing.
• The default lang (language) parameter to ocr and match_text is now configurable. Set lang in the [ocr] section of .stbt.conf.
• press_until_match, detect_motion, wait_for_motion, and is_screen_black can take a new region parameter.
• The mask parameter to detect_motion, wait_for_motion, and is_screen_black can be an OpenCV image (previously it could only be a filename). This makes it easier to construct masks programmatically using numpy.
• The MotionResult object returned by detect_motion and wait_for_motion includes the video-frame that was analysed (in the new frame attribute). This allows you to perform additional analysis – for example if there was no motion is the frame black?
• wait_until has two new parameters: predicate and stable_secs. Together they allow waiting for something to stabilise (for example to wait for the position of a moving selection to stop moving).
• wait_until will try one last time after the timeout is reached. This allows you to use a short timeout with operations that can take a long time.
• The is_visible property of stbt.FrameObject subclasses can now call other public properties. Furthermore, the value of is_visible is always a bool, so you don’t have to remember to cast it to bool in your subclass’s implementation.
• The video recording in the test-results now runs at the full frame-rate rather than slowing down during wait_for_match. As a side-effect, if the image processing is particularly slow the annotations won’t appear on the output video. Apart from that caveat, annotations now appear if you got the frame using stbt.get_frame (previously the annotations only appeared if the frames came from a stbt.frames iterator). “Annotations” means the yellow & red rectangles showing the current match or motion region, or text added with draw_text.

v27¶

Minimum version supported by the Stb-tester Platform.