Inferno is an open source tool for testing data exchanges enabled by the Fast Healthcare Interoperability Resources (FHIR) standard. This repository contains the Inferno test tool, as well as the Inferno Community Edition set of tests which provides server testing for a number of FHIR Implementation Guides (IGs). Users can either run existing Community Edition tests from this repository, or author their own tests using Inferno's open testing language.
If you are interested in testing health IT systems for conformance to the ONC Standarized API for Patient and Population Service (§170.315(g)(10)) criterion, please visit the Inferno Program Edition repository. Testing related to this ONC certification criteria is currently maintained separately.
The Office of the National Coordinator for Health IT (ONC) and MITRE are developing Inferno with the goal of accelerating adoption of open standardized health data APIs by providing robust and accessible testing tools. Inferno is an open source project and welcomes contributions from the health IT community.
Inferno Community Edition Tests
The Inferno team is actively developing tests for a number of different FHIR-enabled use cases. This repository currently contains testing for the following implementation guides:
- US Core v3.1.1
- SMART App Launch Framework v1.0.0
- International Patient Summary v1.0.0
- FHIR Bulk Data Access (Flat FHIR) v1.0.1 (via integration with BDT)
- SMART Scheduling Links (Draft Proposal)
For end-to-end testing of the ONC Standarized API for Patient and Population Services criteria, please visit the Inferno Program Edition repository.
Using Inferno
If you are new to FHIR or SMART-on-FHIR, you may want to review the Inferno Quick Start Guide.
Installation and Deployment
Docker Installation
Docker is the recommended installation method for Windows devices and can also be used on Linux and MacOS hosts.
- Install Docker for the host platform as well as the docker-compose tool (which may be included in the distribution, as is the case for Windows and MacOS).
- Download the latest release of the
inferno
project to your local computer on a directory of your choice. - Open a terminal in the directory where the project was downloaded (above).
- Run the command
docker-compose up
to start the server. This will automatically build the Docker image and launch both the ruby server (using unicorn) and an NGINX web server. - Navigate to http://localhost:4567 to find the running application.
If the docker image gets out of sync with the underlying system, such as when new dependencies are added to the application, you need to run docker-compose up --build
to rebuild the containers.
Check out the Troubleshooting Documentation for help.
Native Installation
Inferno can installed and run locally on your machine. Install the following dependencies first:
And run the following commands from the terminal:
# MacOS or Linux
git clone https://github.com/onc-healthit/inferno
cd inferno
bundle install
bundle exec rake db:create db:schema:load
bundle exec rackup
Inferno can then be accessed at http://localhost:4567 in a web browser.
If you would like to use a different port it can be specified when calling rackup
. For example, the following command would host Inferno on port 3000:
rackup -p 3000
Deploying Inferno in a Server Environment
Inferno's default configuration is designed to be lightweight and
run on the users host machine. If you would like to run a shared instance
of Inferno, you can use the docker-compose configuration provided in
docker-compose.postgres.yml
, which attaches Inferno to a Postgres
database to provide more stability when multiple tests are run
simultaniously. This requires higher resource utilization on the host
machine than the default configuration, which uses SQLite for
storage.
To run this configuration, you use docker-compose.postgres.yml
file:
docker-compose -f docker-compose.postgres.yml up --build -d
To stop the service and destroy the containers, run:
docker-compose -f docker-compose.postgres.yml down
This configuration will persist data if the container is stopped or destroyed. If you would like to clear the data in the database, and have it recreated from scratch the next time the application is started, you can run the following commands:
docker-compose -f docker-compose.postgres.yml down
docker volume ls | grep inferno-pgdata # Lists active volumes
docker volume rm inferno-program_inferno-pgdata # Volume name will end in inferno-pgdata
For another example of deploying Inferno in a production environment, review the docker-compose file used to deploy Inferno Program Edition, Inferno Community Edition, and a number of services on https://inferno.healthit.gov/inferno.
Upgrading Inferno
If an Inferno update makes changes to the database schema, migrations will have to be run when updating. Run migrations with:
bundle exec rake db:migrate
The above will migrate the development database. To migrate a production or test database, use:
RACK_ENV=production bundle exec rake db:migrate
RACK_ENV=test bundle exec rake db:migrate
If you are using the provided inferno docker image, migrations will be run automatically.
Reference Implementation
While it is recommended that users install Inferno locally, a reference implementation of Inferno is hosted at https://inferno.healthit.gov
Users that would like to try out Inferno before installing locally can use that reference implementation, but should be forewarned that the database will be periodically refreshed and there is no guarantee that previous test runs will be available in perpetuity.
Supported Browsers
Inferno has been tested on the latest versions of Chrome, Firefox, Safari, and Edge. Internet Explorer is not supported at this time.
Unit Tests
Inferno contains a robust set of self-tests to ensure that the test clients conform to the specification and performs as intended. To run these tests, execute the following command:
RACK_ENV=test bundle exec rake db:create db:schema:load
bundle exec rake test
Inspecting and Exporting Tests
Tests are written to be easily understood, even by those who aren't familiar with Ruby. They can be viewed directly in this repository.
Tests contain metadata that provide additional details and traceability to standards. The active tests and related metadata can be exported into CSV format and saved to a file named testlist.csv
with the following command:
bundle exec rake inferno:tests_to_csv
Arguments can be provided to the task in order to export a specific set of tests or to specify the output file.
bundle exec rake inferno:tests_to_csv[onc,all_tests.csv]
To just choose the module and use the default groups and filename:
bundle exec rake inferno:tests_to_csv[onc]
Running Tests from the Command Line
Inferno provides two methods of running tests via the command line: by directly providing the sequences or running automated scripts
Note: This feature is still in development and we are looking for feedback on features and improvements in ways it can be used
Running Tests Directly
Testing sequences can be run from the command line via a rake task which takes the sequence (or sequences) to be run and server url as arguments:
bundle exec rake inferno:execute[https://my-server.org/data,onc,ArgonautConformance]
Running Automated Command Line Interface Scripts
For more complicated testing where passing arguments is unwieldy, Inferno provides the ability to use a script containing parameters to drive test execution.
The provided example_script.json
shows an example of this script and how it can be used. The execute_batch
task runs the script:
bundle exec rake inferno:execute_batch[script.json]
Inferno also provides a generate_script
rake task which prompts the user for a series of inputs which are then used to generate a script.
The user is expected to provide a url for the FHIR Server to be tested and the module name from which sequences will be pulled.
bundle exec rake inferno:generate_script[https://my-server.org/data,onc]
Caveats
- For
DynamicRegistration
users must provide instructions similar to that provided inexample_script.json
to automate the webdriver. - The
confidential_client
field is a boolean and must be provided astrue
orfalse
Using with Continuous Integration Systems
Instructions and examples are available in the Continuous Integration Section of the Wiki.
Contact Us
The Inferno development team can be reached by email at inferno@groups.mitre.org. Inferno also has a dedicated HL7 FHIR chat channel.
License
Copyright 2021 The MITRE Corporation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.