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

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

Returns

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

Returns

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)

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")