QA/Execution/Web Testing/Docs/Automation/Testcases/AMO POM Libraries/Utilities

Utility classes

TestCaseBreadcrumbs

A TestCaseBreadcrumbs object is a "stack" of two-tuples which are intended as a simple way to save the current index/key/iteration values while working with nested loops. Its string representation could be added to an exception message or printed during 'verbose mode' to create a 'breadcrumb trail' to help troubleshooting.

The first element in each tuple is the label for the option or item type, such as "sort", "persona" or "app". The second element in the tuple is the option's/item's value. An option might have a short value, such as "popular" or "firefox", while an item might combine multiple values such as position in the list, add-on name and ID.

Conceptually the breadcrumbs object behaves like a stack where a label appears only once. New breadcrumbs are always appended to the end. If a new breadcrumb duplicates an existing breadcrumb's label, the breadcrumb with the matching label is replaced and all crumbs after it are discarded.

Most test cases will only need to use the add( ) method.  Sometimes calling str(  ) may be necessar to explictly get a string representation.

METHODS

__str__
The string representation returns the breadcrumbs in the order they exist in the

list. Each breadcrumb is formated in the form "label: value" where label and

value is seperated by a colon. Breadcrumbs are seperated by a comma.

If the breadcrumb list is empty then null string is returned

add( label, value )
Parameters:
label: name of a option or element, such as "sort", "persona", "app"
value: value of the option or item.

If label does not exist as the first element in any breadcrumb the tuple (label, value) is appended to the list. When the label exists then the existing tuple is replaced with (label, value) and all tuples after it in the list are removed.

index( label )
Parameter
label: label to search for in breadcrumbs

Returns the index if the breadcrumb with the label using an exact match. The first breadcrumb is at index 0. Returns None if label was not found.

delete( label  )
Parameter
label: label to search for in breadcrumbs

Deletes breadcrumb with the specified label and all other breadcrumbs after it.
Nothing is deleted when label is not found.

clear_list( )
Resets breadcrumbs to an empty list

Locators

The Locator class provides descriptive methods locator that require value insertion. Some page classes will define an additional class for locators where simple subsitution is not sufficent, such as a listing of items whose index needs an offset (e.g. the n-th item in the list is at index n+1

METHODS

with_option( option )
with_index( element_index )
Inserts a value into a locator using the % operator (e.g string % option). Both methods operate the same.  Both are defined to offer better method name when passing an index# vs. an option value. If a locator requires multiple insertions (e.g an indexed element on an item that's in a listing) a tuple that corresponds to the locator's format can be passed to either method.

is_css_locator( )
Returns True if begins like a CSS locator, with "css=", otherwise returns False

is_xpath_locator( )
Returns True if begins like a Xpath locator, with "/", otherwise returns False

SavedExceptions

The SavedExceptions class provides a holder for exceptions whenever accumulating exceptions is preferred over ending a test case after an exception.

ATTRIBUTES 

exceptions_saved - a list exceptions, stored as strings. New exceptions are appended to the end of the list. Each string is potentially the concatenation of three parts: 1) the exception title, 2) exception detail, 2) breadcrumbs trail. Only the exception title is essential when an exception is saved
exceptions_saved_count - a dictionary of counts of the exception titles.  The attribute is explained further in the save_exception method

breadcrumbs - A TestCaseBreadcrumbs data type to simplfy including a breadcrumb trail with saved exceptions. See the TestCaseBreadcrumbs class for methods.

has_exceptions - True if exceptions_saved is not null, False if it's a null list.

METHODS

save_exception( ex_base, ex_detail  )
Parameters
ex_base: First part of string that's the appended to exceptions_saved. It is also the key for the exceptions_saved_counts entry which is incremented by 1 by the method. Typically the value is a short generic description such as "element X not found" or "element X on pages A and B are different".

ex_detail: The second part of the exception which provides more specifics about the error. It may include the locator for a missing element, or the values and/or regular expression of a failed comparason.  Although it is a required parameter it may be null. It is expected to be a string or a data type with a string representation.

include_breadcrumbs (optional): If True, the default, the breadcrumbs attribute are included as the third part of the exception string. If False or or the breadcrumbs list is empty then nothing is added for the third part.

print_exceptions_to_stderr( test_case_name )
Parameter

test_case_name: normally the test case's __name__ attribute

Prints the saved exceptions to the stderr channel.  The primary steps are:

1. Print "test case:" followed by test_case_name parameter
2. Prints the exceptions_saved_count dictionary entries using the format of the numeric value is followed by the key value (e.g. ex_base parameter in save_exception( )).  The entries are not printed in any particular order.
3. Prints then entries in the exceptions_saved in the order they appear in the list.
4. Raises an exception.

If the exceptions_saved list is empty the methods print the message "no exceptions saved" and skips steps 2-4.