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.

DataFunctions - Data Manipulation

Functions for searching text and converting to other data types.

ATTRIBUTES

Regular expressions for recurring data
RE_LONG_DATE: Regular expression that matches a long date, ex: "January 1, 1999"
RE_MMDDYYYY: Regular expression that matches a mm/dd/yyyy date
RE_COUNT: Regular expression that matches a positive number or 0, optionally with commas
RE_NON_ZERO_COUNT: Regular expression that matches a positive number, optionally with commas
RE_RATING_STARS_PATTERN: Regular expression that matches standardized rating text "rated # out of 5 stars"
RE_PAGE_RESULTS_NUMBERS: Regular expression that matches "# - # of #"

Other constant values
STRF_LONG_DATE: Formator for date.strptime to parse text into a date object

METHODS

combos_from_lists(lists )
Returns a list of all combinations of values from input lists. Each combination in the list returned is a list. Parameters:
lists: list of lists, such as parameter options lists from TCparams

clean_non_ascii( text )
Return text with special characters converted to plain ascii. Non-printable characters are replaced with #<num>; where <num> is their character code.  New-line characters are replaced with the literal "\n".

encode_for_url( text, encoding_method, chars_to_replace )
Returns a string replacing any characters that considered "special" for a URL.
Parameters:
text: string to convert
encoding_method: how characters are replaced. Recognized values are:

• "HEX_CODE" (default) replaces each special character with its hex code value in the format %dd where 'dd' are digits
  
• "DASH" replaces each sequence of special characters with a '-'. 
  
• "UNDERSCORE" replaces each sequence of special characters with a '_'.  It will return "a_b" for the text "a b" or "a & b".
  

chars_to_replace (optional): string of characters that should be replaced. Overrides pre-defined special characters in the method.

If encoding_method is "DASH" and chars_to_replace include space and "&", the input text "a b" or "a & b" will return "a-b".  Similarly, for the same input value the encoding_method "UNDERSCORE" will return "a_b"

text_long_date_to_date( text )
Returns the date, as a date type, found in the text. Expects the text is in long date format (ex: January 1, 2010). Throws an exception if the conversion fails.

find_long_date( text, leadingRegex, trailingRegex)
Returns the string containing the first long date found.
Parameters:
text: text toe be searched.
leadingRegex (optional): regular expression for text that must immediately proceed the date, if specified.
trailingRegex (optional):regular expression for text that must immediately follow the date, if specified.
Any text that matches leadingRegex or trailingRegex is not returned. An exception is thrown if the string match fails.

text_to_integer( text )
Convert text to an integer. Thrown an exception if the conversion fails.

find_count( text, leadingRegex, trailingRegex )

Returns the string containing the first positive integer or 0.
Parameters: text: the string to be searched.
leadingRegex (optional): regular expression for text that must immediately proceed the count, if specified. trailingRegex (optional): regular expression for text that must immediately follow the count, if specified.

Any text that matches leadingRegex or trailingRegex is not returned. An exception is thrown if the string match fails.
find_page_results_tuple( text )
Returns a string three-tuple of the three values found in text that are returned by matching the pattern "# - # of #" where # are positive integers or 0. An exception is thrown if the pattern match fails.