Smart Health Checks Inferno

A testing suite for validating FHIR servers against the Smart Health Checks Implementation Guide. This project is built on the Inferno testing framework and provides automated tests to ensure compliance with the Smart Health Checks IG.

Overview

Smart Health Checks Inferno is designed to validate FHIR servers that implement the Smart Health Checks Implementation Guide. It tests various FHIR resources including:

• Patient
• Practitioner
• Encounter
• Observations (e.g., Blood Pressure, Body Height, Body Weight, Heart Rate, Heart Rhythm, Head Circumference, Waist Circumference, Pathology Result, Smoking Status)
• Questionnaire Responses
• Conditions
• Immunizations
• Medication Statements
• Allergy Intolerances

The test suite validates resource conformance, search capabilities, and reference resolution according to the implementation guide specifications.

Quick Start

1. Install Docker and Docker Compose.
2. From the project root, run:

   make setup
   make run

3. Open http://localhost/ in your browser.

Prerequisites

• Docker
• Docker Compose v2

Installation

Using Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/aehrc/smart-health-checks-inferno.git
   cd smart-health-checks-inferno

2. Set up the project:

   make setup

   This command will:

   • Pull the necessary Docker images
   • Build the project
   • Run database migrations

Running the Application

Using Docker

Start the application:

make run

This will build and start all the necessary services. Once running, you can access the application at http://localhost.

Choosing a validator: HAPI or Aidbox

The test suite validates FHIR resources using a validator service. You can run with either the HAPI (Java) validator (default) or the Aidbox validator.

HAPI validator (default)

The default setup uses the validator-wrapper (HAPI/Java-based FHIR validator). No extra configuration is needed.

make setup
make run

This uses compose.yaml.

Aidbox validator

To run with the Aidbox validator (Aidbox FHIR server + validator worker), set MODE=aidbox and ensure you have a valid Aidbox license.

1. Create a .env file in the project root with your Aidbox license:

   AIDBOX_LICENSE=<you-license-key>

2. Run with Aidbox mode:

   MODE=aidbox make setup
   MODE=aidbox make run

This uses compose.aidbox.yaml, which starts the Aidbox FHIR server and the aidbox-validator worker. The validator is proxied at the same path (/hl7validatorapi), so the Inferno app works the same from the user’s perspective.

Note: Other make targets also respect MODE. For example, to run tests with the Aidbox stack: MODE=aidbox make tests. To stop Aidbox services: MODE=aidbox make stop.

Stopping and Cleanup

To stop services:

make stop

To remove containers:

make down

Development

Generating Test Files

To generate or regenerate test files from the implementation guide (for local development):

make generate_local

Note: The Docker-based target make generate is intended for maintainers and may rely on internal tooling. For most contributors, use make generate_local.

Running Tests

To run the test suite:

make tests

Code Linting

To check code style:

make rubocop

To automatically fix code style issues:

make rubocop-fix

Full Development Restart

To stop, rebuild, and restart the application with freshly generated files for local development, run:

make stop
make down
make generate_local
make setup
make run

Note: The convenience target make full_develop_restart uses the Docker-based generator and may rely on maintainer-only tooling. If it fails, use the sequence above.

Configuration

The project configuration is stored in config.json. Key configuration options include:

• Implementation Guide (IG) details
• Terminology server URL
• Profile configurations
• Resource configurations

At runtime, the terminology server URL is also configurable via the TX_SERVER_URL environment variable in compose.yaml (defaults to https://tx.dev.hl7.org.au/fhir). You can override it by creating a Docker Compose override file or by editing compose.yaml.

Project Structure

• lib/smart_health_checks_test_kit/: Main test kit code
  • generated/: Generated test files based on the implementation guide
  • igs/: Implementation Guide packages and related files used by the validator

Docker Services

The project uses several Docker services:

• inferno: The main application
• inferno-worker: Background worker using Sidekiq
• validator-api: FHIR validator — HAPI (default, compose.yaml) or Aidbox (MODE=aidbox, compose.aidbox.yaml). In Aidbox mode, validator-api-worker (aidbox-validator) also runs.
• nginx: Web server that proxies requests
• redis: Used for caching and background job queuing
• postgres: Database for storing test results

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Links

• Smart Health Checks Implementation Guide
• Report Issues

Walkthrough: How to generate test suites through IG file.

Download the IG .tgz

In this example, lets say we have the IG as 0.4.1.tgz and downloaded to lib\smart_health_checks_test_kit\igs.

Create a new config file

In the main folder create a new config file called config.041.json.

Edit the contents as required.

Example below:

{
  "ig": {
    "version": "0.4.1",
    "link": "https://smartforms.csiro.au/ig/0.4.1/index.html",
    "package_archive_path": "lib/smart_health_checks_test_kit/igs/0.4.1.tgz"
  },
  "suite": {
    "rewrite_igs": "/home/igs/0.4.1.tgz"
  },
  "configs": {
    "generic": {
      "rewrite_profile_url": {
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-patient": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-patient|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-encounter": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-encounter|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-location": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-location|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-practitioner": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-practitioner|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-practitionerrole": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-practitionerrole|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-organization": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-organization|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-relatedperson": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-relatedperson|2.0.0-ballot",
        "http://hl7.org.au/fhir/core/StructureDefinition/au-core-diagnosticresult-path": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-diagnosticresult-path|2.0.0-ballot",
        "http://hl7.org.au/fhir/StructureDefinition/au-specimen": "http://hl7.org.au/fhir/StructureDefinition/au-specimen|5.1.0-preview"
      }
    }
  }
}

Modify the Rakefile

In the main folder, modify the Rakefile's namespace :smart_health_checks do section to include the newly created config file.

config_files = ['./config.041.json']

Modify aidbox_config.rb (if using Aidbox)

Add the aidbox config to include the new IG in the setup.

configurer.add_upload_step(
  '/$upload-fhir-npm-packages',
  './lib/smart_health_checks_test_kit/igs/0.4.1.tgz',
  {
    'Accept' => 'application/json',
    'Authorization' => authorization,
    'Origin' => base_url,
    'Referer' => 'http://localhost:3500/ui/console'
  },
  form_field: 'file'
)

Delete any previously generated files

Under lib\smart_health_checks_test_kit\generated, delete the files that were created in previous sessions.

Perform cleanup and generate resouces

make stop

make down

make setup

make generate

make setup

make run

Note: If using Aidbox, use MODE=aidbox infront of the make commands