This repository contains various tests for EPICS motor drivers against real hardware on the "sinqtest" test instrument. Alternatively, it can also be used to test the hardware itself by using it with drivers which are known to pass the tests.

The general architecture of the framework is as follows:

ioc contains all files used to create the IOC used in the tests.
tests contains the tests itself in a hierarchical order:
- tests/. contains tests and configuration applicable for any motor record-based driver.
- tests/sinqMotor/. contains tests and configuration applicable for drivers based on https://gitea.psi.ch/lin-epics-modules/sinqMotor
- tests/sinqMotor/turboPmac/. contains tests and configuration applicable for the sinqMotor-based Turbo PMAC driver https://gitea.psi.ch/lin-epics-modules/turboPmac
- tests/sinqMotor/masterMacs/. contains tests and configuration applicable for the sinqMotor-based MasterMACS driver https://gitea.psi.ch/lin-epics-modules/mastermacs Individual motors at the test instrument are then set up as subfolders of their respective driver type.
common.py contains classes representing the motors. They are used to initialize the individual motors within the tests directory.
config.yaml is the test configuration (see Configuration)
maketestenv can be used to create a Python virtual environment for running the tests.

Configuration

The test setup is defined in config.yaml. This file contains information which needs to be shared between the IOC and the tests.

pvprefix: EPICS PV prefix of the IOC records. This information is used to create the full identifier of the records created by the motor drivers.
versions: Driver versions used in the IOC
controllers: Configuration of the different motor controllers (IP + port and poll periods)

Starting the IOC

It is recommended to start the IOC via ioc/startioc.py:

ioc/startioc.py

This file uses config.yaml to generate / overwrite a file ioc/config.cmd. It then starts ioc/st.cmd, which in turn imports ioc/config.cmd to get the current configuration.

Running the tests

General

Running tests requires the following three steps:

Starting the IOC via ioc/startioc.py (see Configuration)
Creating (if not done previously) and activating a suitable virtual environment:

bash
./maketestenv
source testenv/bin/activate

Running the desired test(s) via pytest. For example:

pytest tests/sinqMotor/turboPmac/

This runs all Turbo PMAC tests within the directory.

To run a specific test file:

pytest tests/sinqMotor/turboPmac/lin1/test_common.py

And to run a specific test "test_something" within this file:

pytest tests/sinqMotor/turboPmac/lin1/test_common.py -k 'test_something'

Pytest normally suppresses stdout (which is where Pythons print writes by default). To show it, use the -s flag:

pytest -s tests/sinqMotor/turboPmac/lin1/test_common.py -k 'test_something'

Parallelizing tests over motors

Tests which don't run on the same motor can be parallelized in order to both save on runtime and to test controller and driver performance while handling multiple motors. To do so, the wrapper script pytestpar.py is provided which starts a pytest process for each motor. The individual tests for each motor are run sequentially.

pytestpar.py accepts any arguments and forwards them to the pytest call. If a folder is given as an argument, all tests which are not within this folder are ignored.

pytestpar will run all tests parallelized per motor
pytestpar tests/sinqMotor/turboPmac will run all Turbo PMAC tests parallelized per motor
pytestpar tests/sinqMotor/turboPmac/ax1 will only run the tests for motor ax1. These tests are run sequentially.

Running custom scripts

The test framework can also be used to run custom scripts. The file example_custom_script.py contains a simple example, which can be run by activating the virtual environment and then simply executing it:

bash
source testenv/bin/activate
./example_custom_script.py