Orthanc - A Lightweight, RESTful DICOM Server
=============================================


General Information
===================

This repository contains the integration tests that are used to
validate Orthanc before each official release, in complement to the
unit tests that are part of the Orthanc core repository. These
integration tests should be run by the package maintainers of the
various platforms supported by Orthanc.

General information about Orthanc can be found on its official
Website: http://www.orthanc-server.com/

Prerequisites:
=============

For python2.7 tests, you need the following package
# pip2 install easywebdav httplib2 pillow pydicom==1.4.1 pynetdicom==1.5.6

For python3 tests, you need the following package
# pip3 install httplib2 pillow pydicom pynetdicom

You also need DCMTK and Dicom3Tools
# sudo apt-get install -y dicom3tools dcmtk libgdcm-tools 

Quick-start: Running tests on the localhost 
===========================================

This section explains how to run the integration tests in the simplest
framework. First, install Orthanc. Then, open 2 command shells and
run the instructions that follow:

1. In the first command shell:

# python ./GenerateConfigurationForTests.py --force
# Orthanc IntegrationTestsConfiguration.json

2. In the second command shell:

# python ./Tests/Run.py

to run a single test:

# python Tests/Run.py Orthanc.test_findscu_counters

To test the worklist plugin
---------------------------

1. In the first command shell:

# python ./GenerateConfigurationForTests.py --force --plugins /home/.../libModalityWorklists.so
# Orthanc IntegrationTestsConfiguration.json

2. In the second command shell:

# python ./Plugins/Worklists/Run.py



Running the tests
=================

The integration tests are written in Python and are started by the
"./Tests/Run.py" script. The tests will validate some "remote"
instance of Orthanc (whose AET is "ORTHANC") that is assumed to be
running before the tests are started.

To test the DICOM protocol, a second, "local" instance of Orthanc is
automatically started by the integration tests (its AET is
"ORTHANCTEST"). This situation is depicted on the following
illustration:


+--------------------------+               +-----------------------+
| Local computer           |               | Remote computer       |
+--------------------------+      HTTP     +-----------------------+
|                          |  5000 : 8042  |                       |
| Run.py <---> ORTHANCTEST <===============> ORTHANC               |
|                          |  5001 : 4242  |                       |
+--------------------------+     DICOM     +-----------------------+


Obviously, Orthanc must be installed both on the local and remote
computers.

NB: Of course, the "local" and "remote" computers are allowed be the
same computer.



1. Configure the remote Orthanc
-------------------------------

To run the integration tests, you first have to create a configuration
file for the remote instance of Orthanc. This is done by running the
"./GenerateConfigurationForTests.py" script on the *local*
computer. This script will try and autodetect the proper network
parameters. For instance (a help is available):

# ./GenerateConfigurationForTests.py --force

This will create the "./IntegrationTestsConfiguration.json"
configuration file that must be copied to the remote computer. Then,
start Orthanc on the remote computer using this configuration file.

By default, the configuration file will use "ORTHANC" as the AET, 8042
as the HTTP port, and 4242 as the DICOM port. You can of course
adapt these parameters by editing the generated configuration file,
if you have special constraints or if the autodetection fails.



2. Start the integration tests on the local computer
----------------------------------------------------

Once the remote instance of Orthanc is up and running, you can start
the integration tests. You have 2 possibilities: (a) use your local
computer as is, or (b) use Docker to have the best reproducibility.


(Option 2a) Without Docker:

# python ./Tests/Run.py

To run a single test with by fixing the Orthanc 0.8.6 executable path:
# python2 ./Tests/Run.py --force --orthanc /home/alain/Releases/Orthanc-0.8.6/Build/Orthanc Orthanc.test_peer_store_straight

To run a plugin test (no need for Orthanc 0.8.6)
# python2 ./Plugins/DicomWeb/Run.py --force
# python2 ./Plugins/DicomWeb/Run.py --force Orthanc.test_forwarded_headers

Use the flag "--help" to get the full list of arguments. These
arguments will notably allow you to specify the network parameters
of your remote instance of Orthanc.

To run the IngestTranscoding tests:
# rm -rf /tmp/OrthancTest && python ./Tests/CheckIngestTranscoding.py /home/alain/o/build/orthanc/orthanc

To run the DICOM TLS tests without Client certificate checks:
# cd ./Tests
# python CheckDicomTls.py --config-no-check-client
# /home/alain/o/build/orthanc/Orthanc --verbose dicom-tls.json
#### or
# docker run -p 8042:8042 -p 4242:4242 -e ORTHANC__DICOM_TLS_ENABLED=true -e ORTHANC__DICOM_TLS_CERTIFICATE=/certs/dicom-tls-a.crt -e ORTHANC__DICOM_TLS_PRIVATE_KEY=/certs/dicom-tls-a.key -e ORTHANC__DICOM_TLS_REMOTE_CERTIFICATE_REQUIRED=false -e ORTHANC__DICOM_TLS_TRUSTED_CERTIFICATES=/certs/dicom-tls-trusted.crt -e ORTHANC__EXECUTE_LUA_ENABLED=true -v .:/certs/ -e ORTHANC__AUTHENTICATION_ENABLED=false -e VERBOSE_ENABLED=true orthancteam/orthanc:24.6.1
# python CheckDicomTls.py --force OrthancNoCheckClient

To run the DICOM TLS tests without Client certificate checks:
# cd ./Tests
# python CheckDicomTls.py --config-check-client
# /home/alain/o/build/orthanc/Orthanc --verbose dicom-tls.json
#### or
# docker run -p 8042:8042 -p 4242:4242 -e ORTHANC__DICOM_TLS_ENABLED=true -e ORTHANC__DICOM_TLS_CERTIFICATE=/certs/dicom-tls-a.crt -e ORTHANC__DICOM_TLS_PRIVATE_KEY=/certs/dicom-tls-a.key -e ORTHANC__DICOM_TLS_REMOTE_CERTIFICATE_REQUIRED=true -e ORTHANC__DICOM_TLS_TRUSTED_CERTIFICATES=/certs/dicom-tls-trusted.crt -e ORTHANC__EXECUTE_LUA_ENABLED=true -v .:/certs/ -e ORTHANC__AUTHENTICATION_ENABLED=false -e VERBOSE_ENABLED=true orthancteam/orthanc:24.6.1
# python CheckDicomTls.py --force OrthancCheckClient



(Option 2b) With Docker:

# sudo docker pull jodogne/orthanc-tests
# ./Start.sh

Note that you will have to grant root access for Docker.


(Option 2c) On Windows:

Easiest way to run the integration test under windows is actually
run the remote Orthanc and the python script under WSL and run the
orthanc under test on Windows (such that you can debug it).
Note that if Orthanc on Windows is not using the standard port, you
may specify them when starting the test as shown below

# bash
# python2 Tests/Run.py --force --dicom 4242 --rest 8042 --orthanc /home/alain/Releases/Orthanc-0.8.6/Build/Orthanc Orthanc.test_peer_store_straight

Note that you will have to install Linux prerequisites under WSL
and the orthanc package as well.


NewTests
========

Check the README in the NewTests folder for more complex scenarios
using python3 and a new test framework.


Contributing
============

Instructions for contributing to the Orthanc project are included in
the Orthanc Book:
https://orthanc.uclouvain.be/book/developers/repositories.html


Licensing
=========

The integration tests are licensed under the GPLv3 license. The sample
DICOM images contained in the "Database" folder are the property of
their respective owners, as listed in the "Database/README.txt" file.

We also kindly ask scientific works and clinical studies that make
use of Orthanc to cite Orthanc in their associated publications.
Similarly, we ask open-source and closed-source products that make
use of Orthanc to warn us about this use. You can cite our work
using the following BibTeX entry:

@Article{Jodogne2018,
  author="Jodogne, S{\'e}bastien",
  title="The {O}rthanc Ecosystem for Medical Imaging",
  journal="Journal of Digital Imaging",
  year="2018",
  month="May",
  day="03",
  issn="1618-727X",
  doi="10.1007/s10278-018-0082-y",
  url="https://doi.org/10.1007/s10278-018-0082-y"
}