API

Test

class mats.Test(moniker: str, min_value: Number | None = None, max_value: Number | None = None, pass_if: str | bool | int | None = None, significant_figures: int = 4, loglevel=20)

The most basic unit of an executing test sequence.

Within a test, we may have a setup(), execute(), and teardown() method. Only the execute() method is required to be overridden.

Parameters:

• moniker – a shortcut name for this particular test

• min_value – the minimum value that is to be considered a pass, if defined

• max_value – the maximum value that is to be considered a pass, if defined

• pass_if – the value that must be present in order to pass, if defined

• significant_figures – the number of significant figures appropriate to the measurement

• loglevel – the logging level to apply such as logging.INFO

abort()

Causes current test status to abort

Returns:

None

property criteria

Returns the test criteria as a dict

Returns:

test criteria as a dict

execute(is_passing: bool)

Abstract method intended to be overridden by subclass

Parameters:

is_passing – True if the test sequence is passing up to this point, else False

Returns:

value to be appended to the sequence dictionary

fail()

When called, will cause the test to fail.

Returns:

None

property is_passing

Returns True if test is currently passing, else False

Returns:

True if passing, else False

reset()

Reset the test status :return: None

save_dict(data: dict)

Allows a test to save additional data other than that returned by execute()

Parameters:

data – key: value pairs of the data to be stored

Returns:

None

setup(is_passing: bool)

Abstract method intended to be overridden by subclass

Parameters:

is_passing – True if the test sequence is passing up to this point, else False

Returns:

None

teardown(is_passing: bool)

Abstract method intended to be overridden by subclass

Parameters:

is_passing – True if the test sequence is passing up to this point, else False

Returns:

None

TestSequence

class mats.TestSequence(sequence: list[mats.test.Test], archive_manager: ArchiveManager | None = None, auto_run: int | None = None, callback: callable | None = None, setup: callable | None = None, teardown: callable | None = None, on_close: callable | None = None, loglevel=20)

The sequence or stack of Test objects to execute.

The TestSequence will “knit” the sequence together by taking the test objects and appropriately passing them through the automated testing process.

Parameters:

• sequence – a list of Tests

• archive_manager – an instance of ArchiveManager which will contain the path and data_format-specific information

• auto_run – an integer that determines how many times a test sequence will be executed before stopping

• callback – function to call on each test sequence completion; callback will be required to accept one parameter, which is the dictionary of values collected over that test iteration

• setup – function to call before the test sequence

• teardown – function to call after the test sequence is complete, even if there was a problem; common to have safety issues addressed here

• on_close – function to call when the functionality is complete; for instance, when a GUI closes, test hardware may need to be de-allocated

• loglevel – the logging level

abort()

Abort the current test sequence.

Returns:

None

close()

Allows higher level code to call the close functionality.

property failed_tests: list[str]

Return a list of the tests which failed.

Returns:

list of tests that failed

property in_progress: bool

Returns True if the test sequence is currently in progress, else False.

Returns:

True if the test sequence is currently in progress, else False

property is_aborted: bool

Returns True if the test sequence has been aborted, else False

Returns:

True or False

property is_passing: bool

Returns True if the test sequence is currently passing, else False

Returns:

True or False

property progress: tuple[int, int]

Returns a tuple containing (current_test_number, total_tests) in order to give an indication of the progress of the test sequence.

Returns:

tuple containing (current_test_number, total_tests)

property ready: bool

Returns True if the test sequence is ready for another go at it, False if not

Returns:

True or False

start()

Start a test sequence. Will only work if a test sequence isn’t already in progress.

Returns:

None

property test_names: list[str]

Returns the names of the tests contained within the TestSequence

Returns:

the names of the tests as a list

property tests: list[mats.test.Test]

Returns instances of all tests contained within the TestSequence

Returns:

all tests as a list

ArchiveManager

class mats.ArchiveManager(path: str | Path = '.', fname: str = 'data.txt', delimiter: str = '\t', data_format: int = 0, preamble: str | None = None, loglevel=20)

The default data manager that saves data in a text format which is very flexible, yet maintains simplicity and compatibility with analysis tools such as pandas.

Parameters:

• path – a string or Path containing the path to the data file

• fname – data file name

• delimiter – the data delimiter

• data_format – an integer that determines which data format

• preamble – a string that may be appended to the beginning of a data file

• loglevel – the logging level

aggregate(datetime: datetime, is_passing: bool, failed: list[str], tests: list[mats.test.Test])

Collects data set from provided information and from the tests and organizes the data into a dict in preparation for saving a row of data.

Parameters:

• datetime – the datetime that the test started

• is_passing – True/False/None indicating if the test passed, failed, or was aborted

• failed – a list of test monikers that failed

• tests – a list of tests representing the test sequence

Returns:

save(point: dict)

Data save function

Takes a point of data supplied as a dict and, depending on existing conditions, will archive the data point on the disk. Each point represents a single row of data representing the execution of a single instance of the test execution. Each key of the dict has will represent the parameter being measured.

Three conditions possible at save time:

• Data file does not exist

• Data file exists and is compatible with the current data point (the headings and header strings match)

• Data file exists, but is not compatible with the current data point (the heading and header strings do not match)

When the data file does not exist, then the save() method will create the new data file at <fname>.<extension>.

When the data file exists at <fname>.<extension> and is compatible with the current data point, then the save() method will simply append the new data point to previous data in a tabular data_format.

Finally, when the current data point is deemed incompatible with the previous data, then the save() method will copy the old file to <fname>_<date>.<extension> and then create a new file at <fname>.<extension> under which data will be collected until a new data_format is once again detected.

Parameters:

point – a dict containing key: value pairs which specify the data to be saved in {‘heading’: {‘value’: value}}; the inner dictionary may also contain a dict called criteria which will contain the pass_if, min, or max values allowed

Returns:

None

tkwidgets.MatsFrame

class mats.tkwidgets.MatsFrame(parent, sequence: TestSequence, vertical: bool = True, start_btn: bool = True, abort_btn: bool = True, wrap: int = 6, loglevel=20)

The frame that interacts with the test sequence to display the test results as the test is executing.

Parameters:

• parent – the tk parent frame

• sequence – the instance of TestSequence to monitor

• vertical – if True, will stack tests vertically; otherwise, horizontally; default is vertical, True

• start_btn – if True, will populate a start button; otherwise, will not; default is True

• abort_btn – if True, will populate an abort button; otherwise, will not; default is True

• wrap – the number above which will start the next row or column

• loglevel – the logging level, for instance ‘logging.INFO’