Getting Started
Table of Contents
Getting Started for Inferno Users
Start here if you’re interested in testing a FHIR server against one or more existing Test Kits.
Running an Existing Test Kit
Most Test Kits are developed using the Inferno Template repository which provides scripts for standing up an instance of Inferno to run a selected Test Kit.
- Install Docker.
- Clone the repository for the Test Kit you want to run.
- Run
./setup.sh
in the Test Kit repository directory to retrieve the necessary docker images and create a database. - Run
./run.sh
to start Inferno. - Navigate to
http://localhost
to access Inferno.
e.g., to run the US Core Test Kit:
git clone https://github.com/inferno-framework/us-core-test-kit.git
cd us-core-test-kit
./setup.sh
./run.sh
Always check the documentation for an individual Test Kit since there may be additional installation steps.
Multiple Test Kits
There may be times when you wish to offer multiple test kits in a single Inferno instance. You can load and run two or more separate Test Kits by using Inferno Template.
To create and deploy a custom combination of Test Kits with the Inferno Template first create a new repository based off the template or clone the template:
git clone https://github.com/inferno-framework/inferno-template.git
Add Test Kits you want to include to the Gemfile
:
# Gem published on rubygems
gem 'smart_app_launch_test_kit'
# Gem available via git
gem 'us_core_test_kit',
git: 'https://github.com/inferno-framework/us-core-test-kit.git',
branch: 'main'
To enable the Test Kits, require them in in lib/inferno_template.rb
:
require 'smart_app_launch_test_kit'
require 'us_core_test_kit'
Inferno relies on external validation services for profile validation; by default, Inferno uses the FHIR Validator Wrapper. For Test Kits that require profile validation, such as the US Core Test Kit, the corresponding Implementation Guide will need to be placed in the lib/inferno_deployment/igs/
directory as a .tgz file (i.e., package.tgz). The Implementation Guide files for a Test Kit can be located in that kit’s git repository and just copied over directly:
e.g., for the US Core Test Kit:
git clone https://github.com/inferno-framework/us-core-test-kit.git
cp -a us-core-test-kit/lib/us_core_test_kit/igs/. inferno-template/lib/inferno_template/igs/
Once this is done you can build and run the instance:
cd inferno_template
./setup.sh
./run.sh
Note: Example Test Suites, Groups, Tests and IGs in the template can be removed.
Getting Started for Inferno Test Writers
Tests can be developed with or without a local ruby installation using docker. However, it is highly recommended that you install ruby locally for development. The advantages of using a local ruby installation are
- It is much faster to restart native ruby processes than to stop/rebuild/start docker images. This must be done every time tests change.
- It is possible to set breakpoints and access an interactive debugger inside of running tests, which makes test development much easier.
- The Inferno Command Line Interface can be used. Run
inferno help
for information.
FHIR Validation Setup
Put the package.tgz
for the IG you’re writing tests for in lib/your_test_kit_name/igs
and update this path in docker-compose.background.yml
. This will ensure that the validator has access to the resources needed to validate resources against your IG.
Development with Ruby
Installation
- Install Docker.
- Install Ruby. It is highly recommended that you install ruby via a ruby version manager.
- Install Docker.
- Clone the Inferno Template repository. You can either clone this repository directly, or click the green “Use this template” button to create your own repository based on this one.
- Run
bundle install
to install dependencies. - Run
gem install inferno_core
to install inferno. - Run
gem install foreman
to install foreman, which will be used to run the Inferno web and worker processes. - Run
gem install rerun
to install rerun, which will be used to enablewatch
functionality to reload Inferno when a test has been updated. - Run
bundle exec inferno migrate
to set up the database.
Running Inferno
- Run
bundle exec inferno services start
to start the background services. By default, these include nginx, redis, the FHIR validator service, and the FHIR validator UI. Background services can be added/removed/edited indocker-compose.background.yml
. - Run
inferno start --watch
to start Inferno and to reload any time a file changes. Remove thewatch
flag if you would prefer to manually restart Inferno. - Navigate to
http://localhost:4567
to access Inferno, where your test suite will be available. To access the FHIR resource validator, navigate tohttp://localhost/validator
. - When you are done, run
bundle exec inferno services stop
to stop the background services.
Interactive consoles
A local ruby installation also allows you to use pry, a powerful interactive console, to explore and experiment with your tests with inferno console
:
ᐅ bundle exec inferno console
[1] pry(main)> suite = InfernoTemplate::Suite
=> InfernoTemplate::Suite
[2] pry(main)> suite.groups
=> [#<Inferno::Entities::TestGroup @id="test_suite_template-capability_statement", @short_id="1", @title="Capability Statement">,
#<InfernoTemplate::PatientGroup @id="test_suite_template-patient_group", @short_id="2", @title="Patient Tests">]
[3] pry(main)> suite.groups.first.tests
=> [#<Inferno::Entities::Test @id="test_suite_template-capability_statement-capability_statement_read", @short_id="1.01", @title="Read CapabilityStatement">]
It is also possible to set a breakpoint using the debug gem within a test’s run
block to debug test behavior:
- Add
require 'debug/open_nonstop'
anddebugger
to set the breakpoint. - Run your tests until the breakpoint is reached.
- In a separate terminal window, run
bundle exec rdbg -A
to access the interactive console.
module InfernoTemplate
class PatientGroup < Inferno::TestGroup
...
test do
...
run do
fhir_read(:patient, patient_id, name: :patient)
require 'debug/open_nonstop'
debugger
assert_response_status(200)
assert_resource_type(:patient)
assert resource.id == patient_id,
"Requested resource with id #{patient_id}, received resource with id #{resource.id}"
end
end
end
end
ᐅ bundle exec rdbg -A
DEBUGGER (client): Connected. PID:22112, $0:sidekiq 6.5.7 [0 of 10 busy]
[18, 27] in ~/code/inferno-template/lib/inferno_template/patient_group.rb
18|
19| run do
20| fhir_read(:patient, patient_id, name: :patient)
21|
22| require 'debug/open_nonstop'
=> 23| debugger
24|
25| assert_response_status(200)
26| assert_resource_type(:patient)
27| assert resource.id == patient_id,
(ruby:remote) self.id
"test_suite_template-patient_group-Test01"
(ruby:remote) self.title
"Server returns requested Patient resource from the Patient read interaction"
(rdbg:remote) inputs
[:patient_id, :url, :credentials]
(ruby:remote) patient_id
"85"
(rdbg:remote) url
"https://inferno.healthit.gov/reference-server/r4"
(rdbg:remote) ls request # outline command
Inferno::Entities::Request#methods:
created_at created_at= direction direction= headers headers= id id= index index= name name=
query_parameters request request_body request_body= request_header request_headers resource response response_body response_body= response_header response_headers
result_id result_id= status status= test_session_id test_session_id= to_hash updated_at updated_at= url url= verb
verb=
instance variables: @created_at @direction @headers @id @index @name @request_body @response_body @result_id @status @test_session_id @updated_at @url @verb
(ruby:remote) request.status
200
(ruby:remote) request.response_body
"{\n \"resourceType\": \"Patient\" ... }"
(rdbg:remote) ? # help command
### Control flow
* `s[tep]`
* Step in. Resume the program until next breakable point.
...
Development with Docker Only
Installation
- Install Docker.
- Clone the Inferno Template repository. You can either clone this repository directly, or click the green “Use this template” button to create your own repository based on this one.
- Run
./setup.sh
in the template repository to retrieve the necessary docker images and create a database.
Running Inferno
After installation, run the ./run.sh
script to start Inferno.
- Navigate to localhost to access Inferno and run test suites.
- Navigate to localhost/validator to access a standalone validator that can be used to validate individual FHIR resources.
Next Steps
Now that Inferno is running, you could learn about the file/directory organization or just start writing tests.