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