API

Main classes

class scope_harness.ScopeHarness

This is the main class for scope harness testing. An instance of it needs to be created using one of the static class methods (new_from_*) before any tests can be performed. The instance of ResultsView provided by results_view property is the entry point for invoking actual queries.

Here is an example of a search request:
harness = ScopeHarness.new_from_scope_list(Parameters([‘my-scope.ini’]) view = harness.results_view view.active_scope = ‘my-scope’ view.search_query = ‘’
static new_from_pre_existing_config((str)arg1) → ScopeHarness :

Creates ScopeHarness instance from scope runtime configuration files in given directory

static new_from_scope_list((Parameters)arg1) → ScopeHarness :

Creates ScopeHarness instance from a configuration provided by an instance of CustomRegistry passed to this factory method

static new_from_system() → ScopeHarness :

Creates ScopeHarness instance using default configuration from the system

class scope_harness.CustomRegistry
start((CustomRegistry)arg1) → None
class scope_harness.Parameters

Parameters for instantiating a CustomRegistry instace

enable_scopes((Parameters)arg1[, (bool)system_scopes=False[, (bool)click_scopes=False[, (bool)oem_scopes=False[, (bool)remote_scopes=False]]]]) → None :

Enable particular types of scopes via named arguments

include_click_scopes((Parameters)arg1) → Parameters :

Enable click scopes

include_oem_scopes((Parameters)arg1) → Parameters :

Enable OEM scopes

include_remote_scopes((Parameters)arg1) → Parameters :

Enable remote scopes from Ubuntu servers

include_system_scopes((Parameters)arg1) → Parameters :

Enable system scopes

class scope_harness.MatchResult

Represents the result of matching and is the final object you want to check in your tests. An instance of MatchResult can be obtained by calling one of the match() methods of ResultMatcher, CategoryMatcher, CategoryListMatcher, DepartmentMatcher and ChildDepartmentMatcher. When implementing tests on top of scope_harness.testing.ScopeHarnessTestCase class, use its assertMatchResult helper method to assert on MatchResult instance.

concat_failures
failure((MatchResult)arg1, (str)arg2) → None
failures
success

Search results matchers

class scope_harness.Category

Represents a read-only view of a category returned by scope

components
empty
icon
id
renderer
result((Category)arg1, (str)arg2) → Result :

Get a Result instance by its uri.

param arg2:uri
type arg2:string
returns:instance of Result
raises:ValueError if uri doesn’t exist
result( (Category)arg1, (int)arg2) -> Result :

Get a Result instance by index.

param arg2:index
type arg2:int
returns:instance of Result
raises:ValueError if index is invalid
results
title
class scope_harness.CategoryListMatcher

Matcher object that holds constraints for matching search categories.

category((CategoryListMatcher)arg1, (CategoryMatcher)arg2) → CategoryListMatcher :

Set the category matcher

has_at_least((CategoryListMatcher)arg1, (int)arg2) → CategoryListMatcher :

Set the minimum number of expected categories

has_exactly((CategoryListMatcher)arg1, (int)arg2) → CategoryListMatcher :

Set the exact number of expected categories

match((CategoryListMatcher)arg1, (object)arg2) → MatchResult :

Match the list of categories

mode((CategoryListMatcher)arg1, (CategoryListMatcherMode)arg2) → CategoryListMatcher :

Set the matching mode, see CategoryListMatcherMode.

class scope_harness.CategoryListMatcherMode

Match mode for category list

class scope_harness.CategoryMatcher

Matcher object that holds constraints for matching search category.

components((CategoryMatcher)arg1, (object)arg2) → CategoryMatcher
has_at_least((CategoryMatcher)arg1, (int)arg2) → CategoryMatcher :

Set the minimum number of categories

Set the header link to match

icon((CategoryMatcher)arg1, (str)arg2) → CategoryMatcher :

Set the icon to match

id
match((CategoryMatcher)arg1, (Category)arg2) → MatchResult

match( (CategoryMatcher)arg1, (MatchResult)arg2, (Category)arg3) -> None

mode((CategoryMatcher)arg1, (CategoryMatcherMode)arg2) → CategoryMatcher :

Set the matching mode, see CategoryMatcherMode.

renderer((CategoryMatcher)arg1, (object)arg2) → CategoryMatcher :

Set the renderer string to match

result((CategoryMatcher)arg1, (ResultMatcher)arg2) → CategoryMatcher
title((CategoryMatcher)arg1, (str)arg2) → CategoryMatcher :

Set the title to match

class scope_harness.CategoryMatcherMode

Match mode for category results

class scope_harness.Result

Represents a read-only view on a result returned by a scope

__getitem__((Result)arg1, (str)arg2) → object :

Get result attribute by name.

Parameters:arg2 (string) – attribute name
Returns:attribute value
Raises:ValueError if not found
__init__()

Raises an exception This class cannot be instantiated from Python

__module__ = 'scope_harness'
__reduce__()
art
attributes
background
dnd_uri
emblem
long_press((Result)arg1) → AbstractView :

Activates the result, as if user long-pressed it. Returns an instance of PreviewView (if result was previewed) or None (if result’s uri was a canned scope query)

Returns:PreviewView or None
mascot
subtitle
summary
tap((Result)arg1) → AbstractView :

Activates the result, as if user tapped it. Returns an instance of PreviewView (if result was previewed) or ResultsView (if result’s uri was a canned scope query, resulting in a new search)

Returns:instance of PreviewView or ResultsView
tap_action((Result)arg1, (str)arg2) → AbstractView :

Activates result action. Returns the ResultsView where affected result may potentially be updated.

title
uri
class scope_harness.ResultMatcher

Matcher object that holds constraints for matching search result.

art((ResultMatcher)arg1, (str)arg2) → ResultMatcher :

Set the art to match

attributes((ResultMatcher)arg1, (object)arg2) → ResultMatcher
background((ResultMatcher)arg1, (object)arg2) → ResultMatcher :

Set the background to match

dnd_uri((ResultMatcher)arg1, (str)arg2) → ResultMatcher :

Set the dnd_uri to match

emblem((ResultMatcher)arg1, (str)arg2) → ResultMatcher :

Set the emblem to match

mascot((ResultMatcher)arg1, (str)arg2) → ResultMatcher :

Set the mascot to match

match((ResultMatcher)arg1, (Result)arg2) → MatchResult

match( (ResultMatcher)arg1, (MatchResult)arg2, (Result)arg3) -> None

properties((ResultMatcher)arg1, (dict)arg2) → ResultMatcher :

Set multiple properties to match at once (expects a dictionary of names and corresponding values)

property((ResultMatcher)arg1, (str)arg2, (object)arg3) → ResultMatcher :

Set an arbitrary property to match

subtitle((ResultMatcher)arg1, (str)arg2) → ResultMatcher :

Set the subtitle to match

summary((ResultMatcher)arg1, (object)arg2) → ResultMatcher :

Set the summary to match

title((ResultMatcher)arg1, (str)arg2) → ResultMatcher :

Set the title to match

class scope_harness.ResultsView

This is the main class for driving search and inspecting search results. Set search_query property to invoke search, then inspect categories property to access returned categories and their results. Use browse_department method to change active department.

active_scope
alt_department_id
browse_alt_department((ResultsView)arg1, (str)arg2) → Department :

Go to a specific alternate (e.g. the top-right selection filter if provided by the scope) department by id. Returns Department instance.

browse_department((ResultsView)arg1, (str)arg2) → Department :

Go to a specific department by id. Returns Department instance.

categories
category((ResultsView)arg1, (int)arg2) → Category :

Get Category instance by row index

category( (ResultsView)arg1, (str)arg2) -> Category :
Get Category instance by id
customizations
department_id
description
display_name
has_alt_departments
has_departments
icon_hint
query_id
scope_id
search_hint
search_query
session_id
settings
shortcut
class scope_harness.SearchStatus
NO_INTERNET = scope_harness.SearchStatus.NO_INTERNET
NO_LOCATION_DATA = scope_harness.SearchStatus.NO_LOCATION_DATA
OKAY = scope_harness.SearchStatus.OKAY
UNKNOWN = scope_harness.SearchStatus.UNKNOWN
names = {'OKAY': scope_harness.SearchStatus.OKAY, 'NO_LOCATION_DATA': scope_harness.SearchStatus.NO_LOCATION_DATA, 'NO_INTERNET': scope_harness.SearchStatus.NO_INTERNET, 'UNKNOWN': scope_harness.SearchStatus.UNKNOWN}
values = {0: scope_harness.SearchStatus.OKAY, 1: scope_harness.SearchStatus.NO_INTERNET, 2: scope_harness.SearchStatus.NO_LOCATION_DATA, 3: scope_harness.SearchStatus.UNKNOWN}
class scope_harness.ScopeUri

Helper class for creating scope:// uris

department((ScopeUri)arg1, (str)arg2) → ScopeUri :

Set department of this scope uri

query((ScopeUri)arg1, (str)arg2) → ScopeUri :

Set search query string of this scope uri

to_string((ScopeUri)arg1) → str
uri

Department matchers

class scope_harness.ChildDepartment

Represents a read-only view of a child department.

class scope_harness.ChildDepartmentMatcher

Matcher object that holds constraints for matching child departments of a department.

has_children((ChildDepartmentMatcher)arg1, (bool)arg2) → ChildDepartmentMatcher
id
is_active((ChildDepartmentMatcher)arg1, (bool)arg2) → ChildDepartmentMatcher
label((ChildDepartmentMatcher)arg1, (str)arg2) → ChildDepartmentMatcher
match((ChildDepartmentMatcher)arg1, (ChildDepartment)arg2) → MatchResult

match( (ChildDepartmentMatcher)arg1, (MatchResult)arg2, (ChildDepartment)arg3) -> None

class scope_harness.Department

Represents a read-only view of a department returned by a scope. Use id, label, all_label properties to inspect it, and children property or child method to inspect child departments (instances of ChildDepartment). This class supports __getitem__ call, which acts as a shortcut for child(index) method, and responds to __len__ call, so python’s len(department) may be used instead of department.size

all_label
child((Department)arg1, (int)arg2) → ChildDepartment :

Get child department by its index (a number)

children
id
is_hidden
is_root
label
parent_id
parent_label
size
class scope_harness.DepartmentMatcher

Matcher object that holds constraints for matching departments.

all_label((DepartmentMatcher)arg1, (str)arg2) → DepartmentMatcher :

Set the department alternate (the ‘all’ variant’) label to match

child((DepartmentMatcher)arg1, (ChildDepartmentMatcher)arg2) → DepartmentMatcher :

Set the matcher for child department

has_at_least((DepartmentMatcher)arg1, (int)arg2) → DepartmentMatcher :

Set the minimum number of departments

has_exactly((DepartmentMatcher)arg1, (int)arg2) → DepartmentMatcher :

Set the exact number of departments

id((DepartmentMatcher)arg1, (str)arg2) → DepartmentMatcher :

Set the department id to match

is_hidden((DepartmentMatcher)arg1, (bool)arg2) → DepartmentMatcher :

Set the ‘hidden’ flag to match

is_root((DepartmentMatcher)arg1, (bool)arg2) → DepartmentMatcher :

Set the ‘root’ flag to match

label((DepartmentMatcher)arg1, (str)arg2) → DepartmentMatcher :

Set the department name (label) to match

match((DepartmentMatcher)arg1, (Department)arg2) → MatchResult :

Match the department

match( (ResultMatcher)arg1, (MatchResult)arg2, (Department)arg3) -> None :
Match the department
mode((DepartmentMatcher)arg1, (DepartmentMatcherMode)arg2) → DepartmentMatcher :

Set the matching mode, see DepartmentMatcherMode.

parent_id((DepartmentMatcher)arg1, (str)arg2) → DepartmentMatcher :

Set the id of parent department to match

parent_label((DepartmentMatcher)arg1, (str)arg2) → DepartmentMatcher :

Set the label of parent department to match

class scope_harness.DepartmentMatcherMode

Match mode for departments

Preview matchers

class scope_harness.PreviewColumnMatcher
column((PreviewColumnMatcher)arg1, (PreviewMatcher)arg2) → PreviewColumnMatcher
match((PreviewColumnMatcher)arg1, (object)arg2) → MatchResult

match( (PreviewColumnMatcher)arg1, (MatchResult)arg2, (object)arg3) -> None

class scope_harness.PreviewMatcher
match((PreviewMatcher)arg1, (PreviewWidgetList)arg2) → MatchResult

match( (PreviewMatcher)arg1, (MatchResult)arg2, (PreviewWidgetList)arg3) -> None

widget((PreviewMatcher)arg1, (PreviewWidgetMatcher)arg2) → PreviewMatcher
class scope_harness.PreviewView

This is a view on a preview returned by activation of search Result. Set column_count property to the desired number of columns, then inspect widgets in every column using widgets_in_column(index) method.

column_count
widgets
widgets_in_column((PreviewView)arg1, (int)arg2) → PreviewWidgetList :

Get list of PreviewWidget objects in given column (integer index)

widgets_in_first_column
class scope_harness.PreviewWidget

This class represents a single widget of a preview, such as an image or header. The ‘data’ property is a regular python dictionary that corresponds to Scopes API VariantMap and contains actual key-values that constitute the widget. See the documentation of Unity Scopes API for more information about supported values.

data
id
trigger((PreviewWidget)arg1, (str)arg2, (object)arg3) → AbstractView :

Trigger preview action.

Parameters:
  • arg2 (string) – action identifier
  • arg3 (dict) – dictionary holding additional action data, typically the value of data property.
Returns:

instance of PreviewView or ResultsView.

Raises:

ValueError if action couldn’t be executed

type
class scope_harness.PreviewWidgetList

A simple container for preview widgets returned by a scope. The number of widgets can be determined with python’s len() function and individual widgets can be accessed using [] operator. The [] indexing operator supports numeric index values as well as string keys for accessing widgets based on their identifiers. Slices are not supported.

class scope_harness.PreviewWidgetMatcher

Matcher object that holds constraints for matching a preview widget.

data((PreviewWidgetMatcher)arg1, (object)arg2) → PreviewWidgetMatcher :

Set the expected widget definition

match((PreviewWidgetMatcher)arg1, (PreviewWidget)arg2) → MatchResult

match( (PreviewMatcher)arg1, (MatchResult)arg2, (PreviewWidget)arg3) -> None

type((PreviewWidgetMatcher)arg1, (str)arg2) → PreviewWidgetMatcher :

Set the expected widget type.

Settings matchers

class scope_harness.SettingsMatcher

Matcher object that holds constraints for matchins settings (SettingsView) object.

has_at_least((SettingsMatcher)arg1, (int)arg2) → SettingsMatcher
has_exactly((SettingsMatcher)arg1, (int)arg2) → SettingsMatcher
match((SettingsMatcher)arg1, (object)arg2) → MatchResult
mode((SettingsMatcher)arg1, (SettingsMatcherMode)arg2) → SettingsMatcher
option((SettingsMatcher)arg1, (SettingsOptionMatcher)arg2) → SettingsMatcher
class scope_harness.SettingsMatcherMode

Match mode for settings

class scope_harness.SettingsOption

This is a class holding properies of an option

class scope_harness.SettingsOptionMatcher

Matcher object that holds constraints for matching a settings option.

default_value((SettingsOptionMatcher)arg1, (object)arg2) → SettingsOptionMatcher
display_name((SettingsOptionMatcher)arg1, (str)arg2) → SettingsOptionMatcher
display_values((SettingsOptionMatcher)arg1, (object)arg2) → SettingsOptionMatcher
id
option_type((SettingsOptionMatcher)arg1, (SettingsOptionType)arg2) → SettingsOptionMatcher
value((SettingsOptionMatcher)arg1, (object)arg2) → SettingsOptionMatcher
class scope_harness.SettingsOptionType
class scope_harness.SettingsView

This is a view on a scope settings returned by settings() method of ResultsView.

count
options
set((SettingsView)arg1, (str)arg2, (object)arg3) → None :

Set value of an option

Testing module

class scope_harness.testing.ScopeHarnessTestCase(methodName='runTest')

A class whose instances are single test cases.

This class extends unittest.TestCase with helper methods relevant for testing of Unity scopes.

assertMatchResult(match_result)

Assert for MatchResult object that fails if match wasn’t successful and prints conditions which were not met by the matcher.