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 function the same and both exist 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, earch represented by a string. New
exceptions are appended to the end of the list. Each string is potentially the
concatenation of three parts - the exception title, exception detail,
breadcrumbs. Only the exception title is essential when an exception is saved
exceptions_saved_count - the counts of the exception titles, saved as a
dictionary.
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
Parameters:
ex_base: Beginning of the string that's the exception. Is also the key for a
value in exceptions_saved_counts which is incremented whenever an exception is
saved. Typically the parameter value is 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, where the ex_base may often a more generic. Although
it is a required parameter is may be null. It is expected to be a string or a
data type with a str( ) method which returns a string representation.
include_breadcrumbs (optional): if True, the default, the breadcrumbs attribute
are included as the third part of the exception string. Nothing is added to the
exception string if the parameter is False or the breadcrumbs list is empty.
print_exceptions_to_stderr(test_case_name)
prints the saved exceptions to the stderr channel.
Printing consistents of four steps:
1) Print "test case:" followed by the test_case_name parameter
2) Prints the exceptions_saved_count dictionary. For each value the numeric
value is followed by the key value (e.g. ex_base parameter in save_exception( ))
The values 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 steps 2-4 are skipped.