# Motor Driver Tests

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](#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`:

```console
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

Running tests requires the following three steps:
- Starting the IOC via `ioc/startioc.py` (see [Configuration](#starting-the-ioc))
- Creating (if not done previously) and activating a suitable virtual environment:
```console
bash
./maketestenv
source testenv/bin/activate
```
- Running the desired test(s) via pytest. For example:
```console
pytest tests/sinqMotor/turboPmac/
```
This runs all Turbo PMAC tests within the directory.

To run a specific test file:
```console
pytest tests/sinqMotor/turboPmac/lin1/test_common.py
```

And to run a specific test "test_something" within this file:
```console
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:
```console
pytest -s tests/sinqMotor/turboPmac/lin1/test_common.py -k 'test_something'
```

## 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:
```console
bash
source testenv/bin/activate
./example_custom_script.py
```