SST - Actions Reference

Actions to make Selenium tests simple.

Tests are comprised of Python scripts or test case classes.

Files whose names begin with an underscore will not be executed as tests.

Tests drive the browser with Selenium WebDriver by importing and using SST actions.

The standard set of actions are imported by starting the test scripts with:

from sst import actions

Actions that work on page elements take either an element id or an element object as their first argument. If the element you are working with doesn’t have a specific id you can get the element object with the get_element action. get_element allows you to find an element by its id, tag, text, class or other attributes. See the get_element documentation.

Actions:

accept_alert

accept_alert(expected_text=None, text_to_write=None)

Accept a JavaScript alert, confirmation or prompt.

Note that the action that opens the alert should not wait for a page with a body element. This means that you should call functions like click_element with the argument wait=Fase.

Parameters:
  • expected_text – The expected text of the alert. If None, the alert will not be checked.
  • text_to_write – The text to write in the alert prompt. If None, no text will be written.

add_cleanup

add_cleanup(func, *args, **kwargs)

Add a function to be called when the test is completed.

Functions added are called on a LIFO basis and are called on test failure or success.

They allow a test to clean up after itself.

Parameters:
  • func – The function to call.
  • args – The arguments to pass to func.
  • kwargs – The keyword arguments to pass to func.

assert_attribute

assert_attribute(id_or_elem, attribute, value, regex=False)

Assert an the value of an element’s attribute.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • attribute – The name of the attribute to assert.
  • value – The expected value.
  • regex – If True, the value will be used as regular expression.
Raise :

AssertionError if the element doesn’t exist, or if the value is not the expected.

assert_button

assert_button(id_or_elem)

Assert that an element is a button.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t a button.
Returns:The element object.

assert_checkbox

assert_checkbox(id_or_elem)

Assert that an element is a checkbox.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t a checkbox.
Returns:The element object.

assert_checkbox_value

assert_checkbox_value(id_or_elem, value)

Assert the value of a checkbox.

Parameters:
  • id_or_elem – The identifier of the element, or an element object.
  • value – The expected value of the checkbox. Pass True if you want to assert that the checkbox is selected, False otherwise.
Raise :

AssertionError if the element doesn’t exist, if it is not a checkbox, or if the checkbox value is not the expected.

assert_css_property

assert_css_property(id_or_elem, property, value, regex=False)

Assert the value of an element’s CSS property.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • property – The name of the CSS property to assert.
  • value – The expected value.
  • regex – If True, the value will be used as regular expression.
Raise :

AssertionError if the element doesn’t exist, or if the value is not the expected.

assert_displayed

assert_displayed(id_or_elem)

Assert that an element is displayed.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t displayed.
Returns:The element object.

assert_dropdown

assert_dropdown(id_or_elem)

Assert that an element is a drop-down list.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t a drop-down list.
Returns:The element object.

assert_dropdown_value

assert_dropdown_value(id_or_elem, text_in)

Assert the selected option in a drop-list.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • text_in – The expected text of the selected option.
Raise :

AssertionError if the element doesn’t exist, if it isn’t a drop-down list or if the selected text is not the expected.

assert_element

assert_element(tag=None, css_class=None, id=None, text=None, text_regex=None, **kwargs)

Assert that an element exists.

Parameters:
  • tag – The HTML tag of the element.
  • css_class – The value of the class attribute of the element.
  • id – The value of the id attribute of the element.
  • text – The text of the element. If you pass the text argument, you shouldn’t pass the text_regex too.
  • text_regex – A regular expression to look for in the text of the element. If you pass the text_regex argument, you shouldn’t pass the text too.
  • kwargs – Keyword arguments to look for values of additional attributes. The key will be the attribute name.
Raise :

TypeError if you pass both text and text_regex. AssertionError if the element doesn’t exist.

assert_equal

assert_equal(first, second)

Assert that two objects are equal.

assert_not_equal

assert_not_equal(first, second)

Assert that two objects are not equal.

assert_radio

assert_radio(id_or_elem)

Assert that an element is a radio button.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t a radio button.
Returns:The element object.

assert_radio_value

assert_radio_value(id_or_elem, value)

Assert the value of a radio button.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • value – The expected valueof the radio button. Pass True if you want to assert that the radio button is selected, False otherwise.
Raise :

AssertionError if the element doesn’t exist, isn’t a radio button, or the value is not the expected.

assert_table_has_rows

assert_table_has_rows(id_or_elem, num_rows)

Assert the number of rows of a table.

The rows are the <tr> tags inside the <tbody>

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • num_rows – The expected number of rows.
Raise :

AssertionError if the element doesn’t exist, it isn’t a table, it doesn’t have a tbody, or if its number of rows is not the expected.

assert_table_headers

assert_table_headers(id_or_elem, headers)

Assert the headers of a table.

The headers are the <th> tags.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • headers – A sequence of the expected headers.
Raise :

AssertionError if the element doesn’t exist, or if its headers are not the expected.

assert_table_row_contains_text

assert_table_row_contains_text(id_or_elem, row, contents, regex=False)

Assert that a row of a table contains a text.

The row will be looked for inside the <tbody>, to check headers use assert_table_headers.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • row – The row index, starting from 0.
  • contents – A sequence of strings. Each where string will should be the same as the text of the corresponding column.
  • regex – If True, the strings in contents will be used as regular expressions.
Raise :

AssertionError if the element doesn’t exist, it isn’t a table, it doesn’t have a tbody, if the rows number if bigger than the number of rows in the table, or if the row texts doesn’t match the expected.

assert_text

assert_text(id_or_elem, text)

Assert the text of an element.

For text fields, it checks the value attribute instead of the text of the element.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • text – The expected text.
Raise :

AssertionError if the element doesn’t exist or its text is not the expected.

assert_text_contains

assert_text_contains(id_or_elem, text, regex=False)

Assert that the element contains a text.

For text fields, it checks the value attribute instead of the text of the element.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • text – The expected text.
  • regex – If True, text will be used as a regex pattern.
Raise :

AssertionError if the element doesn’t exist or its text doesn’t contain the expected.

assert_textfield

assert_textfield(id_or_elem)

Assert that an element is a textfield, textarea or password box.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t a text field.
Returns:The element object.

assert_title

assert_title(title)

Assert the page title.

Parameters:title – The expected title.
Raise :AssertionError if the title is not the expected.

assert_title_contains

assert_title_contains(text, regex=False)

Assert that the page title contains a text.

Parameters:
  • text – The expected text.
  • regex – If True, text will be used as a regex pattern.
Raise :

AssertionError if the title doesn’t contain the expected text.

assert_url

assert_url(url)

Assert the current URL.

Parameters:url – The expected URL. It can be an absolute URL or relative to the base url.
Raise :AssertionError if the URL is not the expected.

assert_url_contains

assert_url_contains(text, regex=False)

Assert that the current URL contains a text.

Parameters:
  • text – The expected text.
  • regex – If True, text will be used as a regex pattern.
Raise :

AssertionError if the URL doesn’t contain the expected text.

assert_url_network_location

assert_url_network_location(netloc)

Assert the current URL’s network location.

Parameters:netloc – The expected network location. It is a string containing domain:port. In the case of port 80, netloc may contain domain only.
Raise :AssertionError if the network location is not the expected.

check_flags

check_flags(*args)

Skip a test if one of the flags wasn’t supplied at the command line.

Flags are case-insensitive.

Parameters:args – A list of flags to check.

clear_cookies

clear_cookies()

Clear the cookies of the current session.

click_button

click_button(id_or_elem, wait=True)

Click a button.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • wait – If True, this action will wait until a page with a body element is available. Otherwise, it will return immediately after the Selenium refresh action is completed.
Raise :

AssertionError if the element doesn’t exist or isn’t a button.

click_element

click_element(id_or_elem, wait=True)

Click on an element of any kind not specific to links or buttons.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • wait – If True, this action will wait until a page with a body element is available. Otherwise, it will return immediately after the Selenium refresh action is completed.

close_window

close_window()

Closes the current window.

debug

debug()

Start the debugger, a shortcut for pdb.set_trace().

dismiss_alert

dismiss_alert(expected_text=None, text_to_write=None)

Dismiss a JavaScript alert.

Note that the action that opens the alert should not wait for a page with a body element. This means that you should call functions like click_element with the argument wait=Fase.

Parameters:
  • expected_text – The expected text of the alert. If None, the alert will not be checked.
  • text_to_write – The text to write in the alert prompt. If None, no text will be written.

end_test

end_test()

End the test.

It can be used conditionally to exit a test under certain conditions.

execute_script

execute_script(script, *args)

Execute JavaScript in the currently selected frame or window.

Within the script, use document to refer to the current document.

For example:

execute_script('document.title = "New Title"')
Parameters:
  • script – The script to execute.
  • args – A list of arguments to be made available to the script.
Returns:

The return value of the script.

exists_element

exists_element(tag=None, css_class=None, id=None, text=None, text_regex=None, **kwargs)

Check if an element exists.

Parameters:
  • tag – The HTML tag of the element.
  • css_class – The value of the class attribute of the element.
  • id – The value of the id attribute of the element.
  • text – The text of the element. If you pass the text argument, you shouldn’t pass the text_regex too.
  • text_regex – A regular expression to look for in the text of the element. If you pass the text_regex argument, you shouldn’t pass the text too.
  • kwargs – Keyword arguments to look for values of additional attributes. The key will be the attribute name.
Raise :

TypeError if you pass both text and text_regex.

Returns:

True if the element exists, False otherwise.

fails

fails(action, *args, **kwargs)

Check that an action raises an AssertionError.

If the action raises a different exception, it will be propagated normally.

Parameters:
  • action – A function to check.
  • args – The arguments to pass to the action function.
  • kwargs – The keyword arguments to pass to the action function.
Raise :

AssertionError if the action doesn’t raise an AssertionError.

get_argument

get_argument(name, default=default)

Get an argument from the one the test was called with.

A test is called with arguments when it is executed by the run_test. You can optionally provide a default value that will be used if the argument is not set.

Parameters:
  • name – The name of the argument.
  • default – Value that will be used if the argument is not set.
Raise :

LookupError if you don’t provide a default value and the argument is missing.

Returns:

The argument value.

get_base_url

get_base_url()

Return the base URL used by go_to.

get_cookies

get_cookies()

Get the cookies of the current session.

Returns:A set of dicts with the session cookies.

get_current_url

get_current_url()

Get the URL of the current page.

get_element

get_element(tag=None, css_class=None, id=None, text=None, text_regex=None, **kwargs)

Return an element object.

This action will find and return one elements by any of several
attributes.
Parameters:
  • tag – The HTML tag of the element.
  • css_class – The value of the class attribute of the element.
  • id – The value of the id attribute of the element.
  • text – The text of the element. If you pass the text argument, you shouldn’t pass the text_regex too.
  • text_regex – A regular expression to look for in the text of the element. If you pass the text_regex argument, you shouldn’t pass the text too.
  • kwargs – Keyword arguments to look for values of additional attributes. The key will be the attribute name.
Raise :

TypeError if you pass both text and text_regex. AssertionError if no element matches the attributes or if more than one element match.

Returns:

The elements that matches.

get_element_by_css

get_element_by_css(selector)

Return the element that matches a CSS selector.

Parameters:selector – The CSS selector that will be used to search for the element.
Raise :AssertionError if no element matches the selector of if more than one match.
Returns:The elements that matches.

get_element_by_xpath

get_element_by_xpath(selector)

Return the element that matches an XPath selector.

Parameters:selector – The XPath selector that will be used to search for the element.
Raise :AssertionError if no element matches the selector of if more than one match.
Returns:The elements that matches.

get_element_source

get_element_source(id_or_elem)

Get the innerHTML source of an element.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist

get_elements

get_elements(tag=None, css_class=None, id=None, text=None, text_regex=None, **kwargs)

Return element objects.

This action will find and return all matching elements by any of several attributes.

Parameters:
  • tag – The HTML tag of the element.
  • css_class – The value of the class attribute of the element.
  • id – The value of the id attribute of the element.
  • text – The text of the element. If you pass the text argument, you shouldn’t pass the text_regex too.
  • text_regex – A regular expression to look for in the text of the element. If you pass the text_regex argument, you shouldn’t pass the text too.
  • kwargs – Keyword arguments to look for values of additional attributes. The key will be the attribute name.
Raise :

TypeError if you pass both text and text_regex. AssertionError if no element matches the attributes.

Returns:

A list with the elements that match.

get_elements_by_css

get_elements_by_css(selector)

Return all the elements that match a CSS selector.

Parameters:selector – The CSS selector that will be used to search for the elements.
Raise :AssertionError if no element matches the selector.
Returns:A list with the elements that match.

get_elements_by_xpath

get_elements_by_xpath(selector)

Return all the elements that match an XPath selector.

Parameters:selector – The XPath selector that will be used to search for the elements.
Raise :AssertionError if no element matches the selector.
Returns:A list with the elements that match.

get_page_source

get_page_source()

Gets the source of the current page.

get_text

get_text(id_or_elem)

Return the text of an element.

Parameters:id_or_elem – The identifier of the element, or an element object.
Raise :AssertionError if the element doesn’t exist.

get_wait_timeout

get_wait_timeout()

Get the timeout, in seconds, used by wait_for.

get_window_size

get_window_size()

Get the current window size.

Returns:A pair (width, height), in pixels.

go_back

go_back(wait=True)

Go one step backward in the browser history.

Parameters:wait – If True, this action will wait until a page with a body element is available. Otherwise, it will return immediately after the Selenium refresh action is completed.

go_to

go_to(url='', wait=True)

Go to a URL.

Arguement url:The URL to go to. If it is a relative URL it will be added to the base URL. You can change the base url for the test with set_base_url.
Parameters:wait – If True, this action will wait until a page with a body element is available. Otherwise, it will return immediately after the Selenium refresh action is completed.

refresh

refresh(wait=True)

Refresh the current page.

Parameters:wait – If True, this action will wait until a page with a body element is available. Otherwise, it will return immediately after the Selenium refresh action is completed.

reset_base_url

reset_base_url()

Restore the base url to the default.

This is called automatically for you when a test script completes.

retry_on_exception

retry_on_exception(exception, retries=None)

Decorate a function so an exception triggers a retry.

Parameters:
  • exception – If this exception is raised, the decorated function will be retried.
  • retries – The number of times that the function will be retried. If it is None, the function will be retried until the time out set by set_wait_timeout expires.

run_test

run_test(name, **kwargs)

Execute a test, with the specified arguments.

Tests are executed with the same browser (and browser session) as the test calling run_test. This includes whether or not Javascript is enabled.

Before the test is called the timeout and base url are reset, but will be restored to their orginal value when run_test returns.

Parameters:
  • name – The name of the test to run. It is the test file name without the ‘.py’. You can specify tests in an alternative directory with relative path syntax. e.g.: subdir/foo.
  • kwargs – The arguments to pass to the test. Arguments can be retrieved by the test with get_argument.
Returns:

The value of the RESULT variable, if set by the test being run.

save_page_source

save_page_source(filename='pagedump.html', add_timestamp=True)

Save the source of the currently opened page.

It is called automatically on failures when running in -s mode.

Parameters:
  • filename – The name of the file where the page will be dumped.
  • add_timestamp – If True, a timestamp will be added to the filename.
Returns:

The path to the saved file.

set_base_url

set_base_url(url)

Set the URL used for relative arguments to the go_to action.

set_checkbox_value

set_checkbox_value(id_or_elem, new_value)

Set the value of a checkbox.

Parameters:
  • id_or_elem – The identifier of the element, or an element object.
  • new_value – The new value for the checkbox. Pass True if you want to select the checkbox, False otherwise.
Raise :

AssertionError if the element doesn’t exist or if it is not a checkbox.

set_dropdown_value

set_dropdown_value(id_or_elem, text=None, value=None)

Set the value of a drop-down list.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • text – The text of the drop-down option that will be selected. If you pass the text argument, you shouldn’t pass value too.
  • value – The value of the drop-down option that will be selected. If you pass the value argument, you shouldn’t pass text too.
Raise :

AssertionError if the element doesn’t exist, if it isn’t a drop-down list, if you passed both text and value, or if the option is not in the drop-down list.

set_radio_value

set_radio_value(id_or_elem)

Select a radio button.

Parameters:id_or_elem – The identifier of the element, or its element object.
Raise :AssertionError if the element doesn’t exist or isn’t a radio button.

set_wait_timeout

set_wait_timeout(timeout, poll=None)

Set the timeout and poll frequency used by wait_for.

The default timeout at the start of a test is 10 seconds and the poll frequency is 0.1 seconds.

Parameters:
  • timeout – The new timeout in seconds.
  • poll – The poll frequency in seconds. It is how long wait_for should wait in between checking its condition.

set_window_size

set_window_size(width, height)

Resize the current window.

Parameters:
  • width – The new width for the window, in pixels.
  • height – The new height for the window, in pixels.

simulate_keys

simulate_keys(id_or_elem, key_to_press)

Simulate keys sent to an element.

Available keys can be found in selenium/webdriver/common/keys.py

e.g.:

simulate_keys('text_1', 'BACK_SPACE')
Parameters:
  • id_or_elem – The identifier of the element, or an element object.
  • key_to_press – The name of the key to press.
Raise :

AssertionError if the element doesn’t exist.

sleep

sleep(seconds)

Delay execution for the given number of seconds.

Parameters:seconds – The number of seconds to sleep. It may be a floating point number for subsecond precision.

switch_to_frame

switch_to_frame(index_or_name=None)

Switch focus to a frame.

Parameters:index_or_name – The index or the name of the frame that will be focused. If None focus will switch to the default frame.
Raise :Assertion error if the frame couldn’t be found.

switch_to_window

switch_to_window(index_or_name=None)

Switch focus to a window.

Parameters:index_or_name – The index or the name of the window that will be focused. If None focus will switch to the default window.
Raise :Assertion error if the index is greater than the available windows, or the window couldn’t be found.

take_screenshot

take_screenshot(filename='screenshot.png', add_timestamp=True)

Take a screenshot of the browser window.

It is called automatically on failures when running in -s mode.

Parameters:
  • filename – The name of the file where the screenshot will be saved.
  • add_timestamp – If True, a timestamp will be added to the filename.
Returns:

The path to the saved screenshot.

toggle_checkbox

toggle_checkbox(id_or_elem)

Toggle the checkbox value.

Parameters:id_or_elem – The identifier of the element, or an element object.
Raise :AssertionError if the element doesn’t exist or if it is not a checkbox.

wait_for

wait_for(*args, **kwargs)

Wait for an action to succeed.

It is Useful for checking the results of actions that may take some time to complete.

e.g:

wait_for(assert_title, 'Some page title')
Parameters:
  • condition – A function to wait for. It can either be an action or a function that returns False or throws an AssertionError for failure, and returns anything different from False (including not returning anything) for success.
  • args – The arguments to pass to the condition function.
  • kwargs – The keyword arguments to pass to the condition function.
Raise :

AssertionError if condition does not succeed within the timeout. You can set the timeout for wait_for by calling set_wait_timeout

Returns:

The value returned by condition.

wait_for_and_refresh

wait_for_and_refresh(condition, *args, **kwargs)

Wait for an action to succeed.

It is Useful for checking the results of actions that may take some time to complete.

The difference to wait_for is, that wait_for_and_refresh() will refresh the current page with after every condition check.

Parameters:
  • condition – A function to wait for. It can either be an action or a function that returns False or throws an AssertionError for failure, and returns anything different from False (including not returning anything) for success.
  • args – The arguments to pass to the condition function.
  • kwargs – The keyword arguments to pass to the condition function.
Raise :

AssertionError if condition does not succeed within the timeout. You can set the timeout for wait_for by calling set_wait_timeout

Returns:

The value returned by condition.

write_textfield

write_textfield(id_or_elem, new_text, check=True, clear=True)

Write a text into a text field.

Parameters:
  • id_or_elem – The identifier of the element, or its element object.
  • new_text – The text to write.
  • check – If True, a check will be made to make sure that the text field contents after writing are the same as new_text.
  • clear – If True, the field will be cleared before writting into it.