Refget Compliance Suite

Repository for the refget API Compliance document and test suite.

Important URLS

• Refget specification
• Compliance Document
• Compliance utility documentation

Installing the compliance suite

pip3 install refget-compliance

Running the compliance suite natively

The following will generate a HTML report for your server and serve said HTML. It will also generate a tarball locally of the report

refget-compliance report -s https://refget.server.com/ --serve

The following will generate a JSON report of your server:

refget-compliance report -s https://refget.server.com/ --json server.json

Setting --json - will have the compliance suite write the JSON to STDOUT.

Running the compliance suite via docker

Pull the docker image from dockerhub

docker pull ga4gh/refget-compliance-suite:{version}

{version} specifies the version of the docker image being pulled

Spinning up a docker container

docker run -d -p 15800:15800 --name refget-compliance-suite ga4gh/refget-compliance-suite --server https://www.ebi.ac.uk/ena/cram/ --port 15800 --serve

Arguments:

• --server or -s (required). It is the url of the refget server being tested. At least one --server argument is required. Multiple can be provided.
• --serve (optional) It's default value is False. If --serve flag is True then the compliance report will be served on the specified port.
• --port (optional) It's default value is 15800. If --port is specified then this port has to be mapped and published on the docker container by changing the -p option of the docker run command. For example, if --port 8080 is specified, then docker run command will be

docker run -d -p 8080:8080 --name refget-compliance-suite ga4gh/refget-compliance-suite --server https://www.ebi.ac.uk/ena/cram/ --port 8080 --serve

• --json or --json_path (optional) If this argument is '-' then the output json is flushed to standard output. If a valid path is provided then the output is written as a json file at the specified location.
• --file_path_name or -fpn (optional) It's default value is "web". This argument is required to create a ".tar.gz" format of the output json with the specified name.
• --no-web (optional) If --no-web flag is True then the ".tar.gz" output file creation will be skipped.

Running the compliance suite via Workflow Description Language (WDL)

Run the compliance report

dockstore tool launch --local-entry tools/wdl/refget_compliance_suite.wdl --json tools/wdl/refget_compliance_suite_config.wdl.json

Running the compliance suite via Common Workflow Language (CWL)

Run the compliance report

dockstore tool launch --local-entry tools/cwl/refget_compliance_suite.cwl --json tools/cwl/refget_compliance_suite_config.cwl.json

Additional components

Building and uploading the package to PyPI

First complete the following

1. Edit the files and test these changes are working
2. Update setup.py and increment the version number. Remember to use semantic versioning
3. Update CHANGELOG with all the changes you've made
4. Commit the above changes
5. Tag the repo with your version number e.g. git tag -a 'release/1.2.6' -m 'Release v 1.2.6'

Then run the following and provide your user credentials before doing this. This will upload the compliance suite to the test PyPI server.

python3 setup.py sdist bdist_wheel
twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Assuming this works then upload to live PyPI and provide your live login details.

twine upload dist/*

If twine cannot be found on your machine run pip3 install twine or check in $HOME/.local/bin for the binary (sometimes python binaries end up in the .local directory).

Compliance Documentation

To generate this documentation locally, follow these steps:

git clone https://github.com/ga4gh/refget-compliance.git

cd refget-compliance

pip3 install mkdocs

mkdocs serve

Unittests

To run the tests, follow these steps:

Clone the repository and install required packages

git clone https://github.com/ga4gh/refget-compliance.git

cd refget-compliance-suite

pip3 install -r unittests/requirements.txt

Deploy the good and bad mock servers for version 1 and 2 of Refget:

The good mock server is an ideal implementation of refget standard. It runs on port 8989. The bad mock server does not adhere to refget standards and it runs on port 8988. The port numbers can be configured by changing the GOOD_SERVER_V1_URL and BAD_SERVER_V2_URL values in unittests/constants.py file.

python3 unittests/mock_servers/good_mock_server_v1.py &
python3 unittests/mock_servers/good_mock_server_v2.py &
python3 unittests/mock_servers/bad_mock_server_v1.py &
python3 unittests/mock_servers/bad_mock_server_v2.py &

Run the unittests

py.test