Skip to content

Design Principles

The key architectural decisions behind FHIR Frog.

Standards First

FHIR Frog executes the FHIR TestScript and TestPlan specifications as defined by HL7. It does not invent new test formats — TSH and TPH are authoring conveniences that compile to standard FHIR resources. Any FHIR TestScript runner can execute the output.

Separation of Concerns

Each component has one job:

  • Engine orchestrates phases
  • Executors perform operations
  • Evaluators validate responses
  • Managers track state
  • Renderers produce output

This makes each component independently testable and replaceable.

Open Standard Runner

FHIR Frog is designed to be the reference open-source runner for FHIR TestScript. It ships as a fat JAR with no required infrastructure — just Java and a FHIR server.

Tests Ship with the IG

The deployment model is IG-native: TestScripts live in the IG package, not in a separate test repository. This keeps tests in sync with profiles automatically and makes them accessible to every implementer.

Reproducible Test Environments

The Docker commit bootstrap pattern ensures that every test run uses the same pre-warmed FHIR server state, eliminating "works on my machine" failures caused by package loading order or partial downloads.

Client-Side FHIR Resource Space

FHIR Frog operates as a FHIR client that maintains its own resource space during execution. Within this space, all test specification resources (TestScript, TestPlan) are assembled and linked, fixture resources are loaded and their cross-references resolved, variables are managed, and the TestReport is built incrementally as a FHIR resource linked back to the TestScript it is reporting on.

The boundary between the client-side space and the server under test is explicit: FHIR HTTP operations cross it in one direction; responses are captured back into the space. Nothing on the server side is assumed to be part of the test's resource graph.

This model has three consequences:

  • Spec assembly happens client-side — imported TestPlans and their referenced TestScripts are resolved and linked within the space before execution begins.
  • Cross-fixture references are resolved client-side — fixture resources that reference each other have those references rewritten (to urn:uuid: form) before the transaction bundle is submitted to the server.
  • TestReport is a first-class resource — it is built inside the space with a proper FHIR reference to the TestScript, not assembled after the fact from a shadow data structure.

Minimal Dependencies for Consumers

Downstream IGs only need to depend on the fat JAR (Ant) or the library artifact (Maven/JUnit). HAPI FHIR and ANTLR4 are bundled — no transitive dependency conflicts.