Getting Started Creating a Test Kit
This page shows you how to create a Test Kit from scratch. We recommend using the Inferno Template repository as a starting point, since it includes everything you’ll need to get started. You may also create a new Test Kit using the Inferno Command Line Interface (CLI).
We encourage beginners to visit the Inferno Test Kit Authoring Tutorial that walks you through creating a basic set of tests for servers that target a common Implementation Guide.
Tests can be developed either with a local Ruby installation or by using Docker. We recommended installing Ruby locally for development because:
- When the tests change, it is much faster to restart native Ruby processes than to stop/rebuild/start Docker images.
- Ruby lets you set breakpoints and access an interactive debugger inside of running tests, which makes test development easier.
- The Inferno Command Line Interface can be used, which includes additional useful functionality for developers, such as an interactive console. See Inferno CLI for more information.
Development with Ruby
Windows Instructions
Windows developers will need to use WSL in order to interact with Inferno. It is recommended that you also follow the steps for installing node.js. Once you have WSL (and node.js) set up:
- Install VS Code and the WSL Extension.
- Install Ubuntu from the Windows Store.
- Open Command Prompt and run
ubuntu
.- You will have to setup a user and password for this linux subsytem.
- The password will be used for
sudo
commands later, so remember these credentials!
- Install Docker Desktop for Windows.
- Follow the steps from Docker to ensure it plays nicely with WSL, see here.
- From the Docker settings, Open Resources > WSL Integration, and make sure Ubuntu is selected. Then, hit “Apply and Restart”.
- From VS Code, press
Ctrl
+Shift
+P
to open the command palette, and type “WSL”. Select “Connect to WSL in new Window using distro…” and select Ubuntu. - Open a terminal in the new WSL window and try to
ping google.com
. - If you cannot ping google.com, you may not be able to connect to the internet from within the WSL instance. The steps at this stack overflow article should resolve the issue. If it does not, open cmd and run
nslookup
. Copy the Default Address, then in your wsl instance typesudo nano /etc/resolv.conf
. Add the default address as another nameserver. - Continue from step 2 in Set Up Environment.
NOTE: If, when running Inferno within WSL, the tests begin to stall and the console repeatedly prints WARN: Your Redis network connection is performing extremely poorly.
,
WSL may be having networking issues. To resolve this, you can follow the steps in this WSL Slow Network Issue thread. You can make a .wslconfig
file from your %USERDATA%
directory if it does not already exist, and you will need to restart WSL (usually through wsl --shutdown
in Windows Powershell) before the changes take effect.
Set Up Environment
- Install Docker.
- Install Ruby. It is highly recommended that you install Ruby via a Ruby version manager.
- 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.
Set Up a New Test Kit
There are two convenient methods to create a new Test Kit. The first is by cloning the Inferno Template repository. This method ensures you will always be starting with the latest Test Kit Template. You can either clone this repository directly, or click the green “Use this template” button in GitHub to create your own repository based on the Inferno Template.
The second method is to use the Inferno Command Line Interface.
gem install inferno_core && inferno new my-test-kit
This will create a new Test Kit Template in a directory named test-kit-name
. See how to create a new Test
Kit using the Inferno CLI for more
information and options.
- Create your Test Kit by cloning the Inferno Template
or by using the
inferno new
command. - Run
bundle install
to install dependencies. - Run
bundle exec inferno migrate
to set up the database.
Run Your Test Kit
- 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. You can check to make sure they’re running by runningdocker container ls
in the command line, or checking the “Container” tab in Docker Desktop. - Run
inferno start --watch
to start Inferno and have it 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. You should see two test groups on the side of the page: “Capability Statement” and “Patient Tests”. 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.
Development with Docker Only
Set Up Environment
- Install Docker.
Set Up a New Test Kit
- Create your Test Kit by cloning the Inferno Template
or by using the
inferno new
command. - Run
./setup.sh
in the template repository to retrieve the necessary Docker images and create a database.
Run Your Test Kit
- Run the
./run.sh
script to start Inferno.- Navigate to
http://localhost
to access Inferno and run test suites. - Navigate to
http://localhost/validator
to access a standalone validator that can be used to validate individual FHIR resources.
- Navigate to
Next Steps
Now that Inferno is running, you can:
- Go to Template Layout for how to update the template for your use case
- Go to Inferno CLI for
more information about the
inferno
commands available, - Go to Debugging for more information about debugging in Inferno,
- Or just jump to Writing Tests.