Skip to content
Processing Framework

Testing an Engine using splitfixture

Testing an Engine using splitfixture

The splitfixture tool simplifies testing an engine container on a developer’s local workstation. Splitfixture generates the same task request JSON file and directory structure that is presented by the Processing Framework. You can test in two ways - outside a container for local, iterative development and inside a container context.

NOTE: If testing a container, using the python package will be problematic. Be sure to use the splitfixture container!

Testing outside a Container

The developer may prefer to initially debug an engine by running it directly on their workstation rather than in a container. To support this scenario, install the splitfixtue Python package directly on the workstation OS. Installation instructions found here.

The command splitfixture --help displays the help:

Usage: splitfixture [OPTIONS] OPDEF [INPARAMS]...


Arguments:
  OPDEF          Path to a json file defining the operation to test
                 [required]


  [INPARAMS]...  Zero or more Key=value pairs that specify values for the
                 operation's input parameters




Options:
  -p, --port-contents DIRECTORY   Directory that contains sub-directories that
                                  supply the contents of input ports


  -t, --task-scratch DIRECTORY    Directory in the taskScratch volume to write
                                  the request json and ports


  -f, --parameter-file FILE       A file containing key=value pairs, 1 per
                                  line. These supply input parameter values


  --help                          Show this message and exit.

The following command will generate a test fixture for executing the compute_checksums operation.

Terminal window
splitfixture "/integritychecker/operation_definitions/compute_checksum.json" -p "/integritychecker/test_fixtures/empty/source_ports" -t /taskscratch algorithm=md5

Where:

  • "/integritychecker/operation_definitions/compute_checksum.json" is the path to the operation definition JSON file.
  • -p "/integritychecker/test_fixtures/empty/source_ports" specifies the directory that contains input port contents. There should be a sub-directory with the same name as each input port defined by compute_checksum.json. So, in this example, your input file’s path would be /integritychecker/test_fixtures/empty/source_ports/sources/testfile
  • -t /taskscratch Specifies a directory to create the task request JSON and port directories in. If the engine was running in a container this path would point to the shared volume mounted on the container. If not, this directory must already exist.
  • algorithm=md5 specifies md5 as the value of the algorithm parameter.

The output of this command will be a small JSON object that specifies the PF_TASK_JSON_PATH environment variable that must be set so the engine can locate the task request JSON generated by splitfixture.

{"PF_TASK_JSON_PATH": "/taskscratch/request_a47ba2ec-06d4-11ec-b386-0242ac110002.json", "execution-id": "a47ba2ec-06d4-11ec-b386-0242ac110002"}

Running the test fixture is initiated with the command.

Terminal window
export PF_TASK_JSON_PATH=/taskscratch/request_a47ba2ec-06d4-11ec-b386-0242ac110002.json
pythom -m integritychecker

If your engine code will expect environment variables beyond PF_TASK_JSON_PATH they should also be set at this step before running the engine code.

Running Tests on the Engine Container

In order to build a test fixture that can be used by a containerized Engine, splitfixture must also be run from a container. Splitfixture is available as both Windows and Linux Docker images. Instructions for downloading are found here.

The version you use must match the OS type of your Split Engine container. They are differentiated by the image tags (ie windows-latest and linux-latest). The Linux containers are currently based on Debian 11 and all Windows images are based on Windows version 1809 (10.0.17763).

The command to generate a test fixture for the compute_checksum operation using the splitfiure-linux image is:

Terminal window
docker run --rm -t --volume lintask:/taskscratch --volume "/mnt/c/pegasus/split/integritychecker/operation_definitions":/opdef --volume "/mnt/c/pegasus/split/integritychecker/test_fixtures/structure_test/source_ports":/inp trimble/pf-splitfixture:linux-latest /opdef/compute_checksum.json algorithm=sha256

Where:

  • --volume lintask:/taskscratch mounts the lintask volume at /taskscratch. The /taskscratch mount point is used as the shared volume where the task request JSON and port directory structure is created. In this case lintask is a docker volume previously created with the command docker volume create lintask. Any legal volume name is acceptable, it doesn’t have to be named lintask.
  • --volume "/mnt/c/pegasus/split/integritychecker/operation_definitions":/opdef mounts a directory containing operation definition JSON. The later /opdef/compute_checksum.json argument specifies the full path to the operation definition in the mounted volume.
  • --volume "/mnt/c/pegasus/split/integritychecker/test_fixtures/structure_test/source_ports":/inp mounts a directory containing input port contents. There should be a sub-directory with the same name as each input port defined by compute_checksum.json. The directory must be mounted on /inp unless a -p option is supplied to specify a different mount point.
  • trimble/pf-splitfixture:linux-latest is the docker image to run.
  • /opdef/compute_checksum.json specifies the path to the operation definition JSON file. Note that this path is through the /opdef mount point.
  • algorithm=sha256 specifies md5 as the value of the algorithm parameter.

The output of this command will be a small JSON object that specifies the PF_TASK_JSON_PATH environment variable that must be set in the engine container to tell the engine where the request JSON file is located.

{"PF_TASK_JSON_PATH": "/taskscratch/request_33c1a9e6-06d6-11ec-8e65-0242ac110002.json", "execution-id": "33c1a9e6-06d6-11ec-8e65-0242ac110002"}

Running the container test fixture is initiated with the command.

Terminal window
docker run -it --rm --volume lintask:/taskscratch --env PF_TASK_JSON_PATH=/taskscratch/request_33c1a9e6-06d6-11ec-8e65-0242ac110002.json int-engine/integritychecker:latest

Where:

  • --volume lintask:/taskscratch mounts the shared scratch volume. This must be the same volume and mount point used on when generating the test fixture.
  • --env PF_TASK_JSON_PATH=/taskscratch/request_33c1a9e6-06d6-11ec-8e65-0242ac110002.json sets the PF_TASK_JSON_PATH environment variable with the path to the task request JSON file. Note that this path to this file is on the shared /taskscratch volume.
  • int-engine/integritychecker:latest is the Docker image to execute.

Custom Environment Variables

If your executable or tdsplitengine implementation required environment variables as discussed here, they will need to be provided in this docker run command. They can be added in the same way PF_TASK_JSON_PATH was defined above.

Accessing test output data

After a test, the volume will have a directory structure similar to:

lintask/
│   33c1a9e6-06d6-11ec-8e65-0242ac110002.log
│   request_33c1a9e6-06d6-11ec-8e65-0242ac110002.json
│   result_33c1a9e6-06d6-11ec-8e65-0242ac110002.json
│   secondary_logs33c1a9e6-06d6-11ec-8e65-0242ac110002/
└───33c1a9e6-06d6-11ec-8e65-0242ac110002/
    │   inputs/
    │   outputs/

The shared scratch volume lintask is a docker volume, so it is not easily accessible from your local machine. There are a few methods to retrieve and inspect the output data.

Export Script

Run a container with the docker volume and a local volume mounted and copy the docker volume contents to the local volume.

Example bash script

Terminal window
docker run --rm -it \
    --volume lintask:/taskscratch \
    --volume /home/user/output_data:/tmpdata \
    python:3.8-slim-buster \
    bash -c 'cp -a /taskscratch/. /tmpdata/'

Where:

  • --volume lintask:/taskscratch mounts the shared scratch volume. It must be the same volume used in your test.
  • --volume /home/user/output_data:/tmpdata mounts your local directory /home/user/output_data.
  • python:3.8-slim-buster is the image being launched. This can be modified to other local linux containers if needed.

Example powershell script

Terminal window
docker run --rm -it \
    --volume lintask:C:\taskscratch \
    --volume C:\output_data:C:\tmpdata \
    python:3.8-windowsservercore-1809 \
    powershell.exe -command Copy-Item -Path C:\Taskscratch\* -Destination C:\tmpdata -Recurse

Where:

  • --volume lintask:C:\taskscratch mounts the shared scratch volume. It must be the same volume used in your test.
  • --volume C:\output_data:C\tmpdata mounts your local directory C:\output_data. This directory must already exist.
  • python:3.8-windowsservercore-1809 is the image being launched. This can be modified to other local windows containers if needed.
Default file paths

Docker generally saves its volume data in a default location.

  • Linux: /var/lib/docker/volumes/<volume-name>/_data
  • Windows: C:\ProgramData\Docker\volumes\<volme-name>\_data\ However, access to these directories may be restricted to your user account.