SANBlaze Test API Utilities

class LogWatcher(log_file='/var/log/messages', delay=2)

While other blocking actions are performed, provide access to logs created while the action was performed.

add_error(cnt=1)

Increment the error count for the current test

Add 1 to the count in the errors file in the rest tree. This number is not reset between passes.

Returns:

Current total errors after incrementing

Return type:

int

Example

Add an error:

total_errors = add_error()
add_warning()

Increment the warning count for the current test

Add 1 to the count in the warnings file in the rest tree. If allowedwarnings is exceeded the test will automatically be stopped. This number is not reset between passes.

Returns:

Current total warnings after incrementing

Return type:

int

Example

Add a warning:

total_warnings = add_warning()
build_feature_0c_data(itps, itpt, byte_order='big')

Create the data to be sent with Set Features 0Ch

itps and itpt can either be single integers or lists of integers. They must contain the same number of values.

Parameters:
  • itps (int or list) – Idle Transition Power State

  • itpt (int or list) – Idle Time Prior to Transition (milliseconds)

  • byte_order (str) – ‘big’ or ‘little’. Use ‘big’ with XML_API.

bytes_from_int(num, start, end=None, reverse=False, string=False)

Extract the byte range [end:start] from num.

Parameters:
  • num (int) – The number from which to extract the bytes.

  • start (int) – The start of the byte range to extract.

  • end (int) – The end of the byte range to extract. Omit for single byte.

  • reverse (bool) – Reverse the byte order of the returned range.

  • string (bool) – Return the range as a hexadecimal string.

Returns:

The extracted range.

Return type:

int or str

check_result(result, fail_type='error', fail_message='Action failed', success_message=None)

Check if result failed. If so, call fail_action(fail_type, fail_message)

Parameters:
  • result (dict) – The dictionary returned by an XML_API call

  • fail_type (int or str) –

    Specifies the action to be taken if the result is failure

    0 or 'pass' : Log a PASS
    1 or 'notify' : Log a NOTE
    2 or 'warn' : Log a WARNING and increment warnings counter
    3 or 'error' : Log an ERROR and increment errors counter
    4 or 'test' : Log an ERROR and immediately fail the entire test

  • fail_message (str) – The message printed if result is failure. “[fail_message]: [reason]”

  • success_message (str) – The message printed if result is success. Nothing by default

Returns:

0 if the result is success, the failure reason if it failed

Return type:

int or str

check_value_compare(value1, name1, value2, name2='expected value', operation='=', fail_type='error', fail_message='Action Failed', success_message='Action Succeeded', base=None)

Compare the two values using the operators. It will not accept the value that pass as a list or dictionary or tuple.

Parameters:
  • value1 (int or str or float) – The first value to compare. It stays on the LEFT side when comparing between two values.

  • name1 (str) – The name of the first value.

  • value2 (int or str or float) – The first value to compare. It stays on the RIGHT side when comparing between two values.

  • name2 (str) – The name of the second value. The default is ‘expected value’.

  • operation – The operators (=, >, <, >=, <=, !=)

  • fail_type (int or str) –

    Specifies the action to be taken if the result is failure

    0 or 'pass' : Log a PASS
    1 or 'notify' : Log a NOTE
    2 or 'warn' : Log a WARNING and increment warnings counter
    3 or 'error' : Log an ERROR and increment errors counter
    4 or 'test' : Log an ERROR and immediately fail the entire test

  • fail_message (str) – The message printed if result is failure. Default is “Action Failed”

  • success_message (str) – The message printed if result is success. Default is “Action Succeeded”

  • base (int) – The base number is only for printing the output. (ex. 16, 2). Default is base 10.

fail_action(fail_type, message)

Perform the fail_type action and log message

Parameters:
  • fail_type (int or str) –

    Specifies the action to be taken

    0 or 'pass' : Log a PASS
    1 or 'notify' : Log a NOTE
    2 or 'warn' : Log a WARNING and increment warnings counter
    3 or 'error' : Log an ERROR and increment errors counter
    4 or 'test' : Log an ERROR and immediately fail the entire test

  • message (str) – The message logged if result is failure

Return type:

None

fail_test(message=None)

Stop test execution and set test state to Failed. Log message

Parameters:

message (str) – The error message to be logged. Is set to “The test has failed” if None

find_in(result, find, convert=0)

Recursively search result for the dictionary key equal to find

This function is designed to make parsing the results of API calls simple. It searches recursively to find a dictionary key equal to ‘find’, and returns the value of that key if it exists.

Parameters:
  • result (dict or list or tuple) – The nested structure to search

  • find (any) – The dictionary key to search for in result

  • convert (int) –

    Optional. Attempt to convert the found value to one of the following:

    1: integer from decimal string 2: integer from binary string 16: integer from hexadecimal string

    3: string 4: binary string “0b…” 5: hexadecimal string “0x…” 6: float

Returns:

The value associated with the found dictionary key

Return type:

any

Raises:

KeyError – If the dictionary key is not found

Example

Suppose you have a complex nested structure like this (hypothetical):

structure = {'A': {'data': [0, (4, {'info': 6, 'find_this': 1000}), 7], 'other_data': [1, 2, 3]}}

These calls would return the value 1000 contained deep inside:

value = find_in(structure, "find_this")
v_str = find_in(structure, "find_this", 3)   # Convert to str
format_result(result, prt=0)

Print a formatted log page entry in the test log. :meta private: :param result: Result dictionary obtained from an XML_API call :type result: dictionary :param prt: Print the result to the command line :type prt: int

Return type:

Formatted string for printing

Examples

Add the output of a log page to the system log:

result = other_dut.get_logpage(log_id=2, page_control=0, nsid=0)
logging.detail(format_result(result, 1))
get_slot(dut)

Return the system slot of the given dut

Parameters:

dut (XML_API) – The device to get the slot of

Returns:

The system slot of the device

Return type:

int

get_var(name, default, _type=None)

Get value stored in rest tree for test parameter.

Parameters:
  • name (str) – The parameter of interest

  • default (int or str) – Value to return if the file does not exist

Returns:

value – Returns the value stored in the rest tree file. Tries to cast to float, int, and finally string.

Return type:

float, int, or string

Examples

Get the var stored in the passes file. Return ‘unknown’ if it doesn’t exist:

get_var('passes', 'unknown')

Get the var stored in the passes file. Return ‘1’ if it doesn’t exist:

get_var('passes', 1)
ordinal(n)

Convert an integer into its ordinal representation:

ordinal(0)   => '0th'
ordinal(3)   => '3rd'
ordinal(122) => '122nd'
ordinal(213) => '213th'
proc_write(command, into, silent=False)

Write command > into, and read the resulting output.

Parameters:
  • command (str) – The command to be written, such as “reset_ctrl=100”.

  • into (str) – The destination of the command, such as “/proc/vlun/nvme”.

  • silent (bool) – Avoid printing of extra commands.

Returns:

statusint

0 for success, 1 for failure.

reasonstr

The reason for the success or failure.

resultstr

The output from proc, if any.

Return type:

dict

set_var(name, value)

Set the value stored in rest tree for test parameter.

Parameters:
  • name (str) – The parameter of interest

  • value (any) – Value to store in the rest tree

Returns:

value – Returns the value stored in the rest tree file. Tries to cast to float, int, and finally string.

Return type:

float, int, or string

Examples

Get the var stored in the passes file. Return ‘unknown’ if it doesn’t exist:

set_var('passes', 7)

Get the var stored in the passes file. Return ‘1’ if it doesn’t exist:

set_var('errors', 3)
skip_test(message=None)

Stop test execution and set test state to Skipped. Log message

Parameters:

message (str) – The skip message to be logged. Is set to “Skipping test” if None

string_in(result, st)

Recursively search result for the string st

This function is designed to make parsing the results of API calls simple. It searches recursively to find a string equal to st. It returns True if st exists, False otherwise.

Parameters:
  • result (dict or list or tuple or str) – The nested structure to search

  • st (str) – The string to search for in result

Returns:

True if st was found, False otherwise

Return type:

bool

Example

Suppose you have a complex nested structure like this (hypothetical):

structure = {'A': {'data': [0, (4, {'info': 6, 'find_this': 'SANBlaze'}), 7], 'other_data': [1, 2, 3]}}

This call would return True:

exists = string_in(structure, "SANBlaze")