Skip to content

Quick Start

Get up and running with FHIR Frog in 5 minutes.

TestScript Shorthand (TSH)

You can write TestScripts in TSH format - a concise syntax that's much easier to read and write than JSON/XML. See examples below!

Prerequisites

  • Java 17 or later
  • Maven 3.9+
  • A FHIR server (or use Testcontainers)

1. Add Dependency

Add FHIR Frog to your pom.xml:

<dependency>
    <groupId>org.fhirfrog</groupId>
    <artifactId>fhir-frog-library</artifactId>
    <version>0.1.1-SNAPSHOT</version>
    <scope>test</scope>
</dependency>

2. Create a TestScript

Create src/test/resources/fhir/patient-create.tsh:

TestScript: PatientCreate
Title: "Create Patient Test"
Status: #draft

Fixture: patient from "sample-patient.json"

Test: "Create patient"
  * operation create Patient from patient as createResponse
  * assert responseCode = 201
  * assert resource = Patient

Option B: JSON Format

Create src/test/resources/fhir/patient-create.json:

{
  "resourceType": "TestScript",
  "id": "patient-create",
  "name": "PatientCreate",
  "status": "draft",
  "fixture": [{
    "id": "patient",
    "resource": {
      "reference": "sample-patient"
    }
  }],
  "test": [{
    "name": "Create patient",
    "action": [
      {
        "operation": {
          "type": {"code": "create"},
          "resource": "Patient",
          "sourceId": "patient",
          "responseId": "create-response"
        }
      },
      {
        "assert": {
          "response": "created",
          "sourceId": "create-response"
        }
      }
    ]
  }]
}

3. Create Test Fixture

Create src/test/resources/fhir/sample-patient.json:

{
  "resourceType": "Patient",
  "name": [{
    "family": "Smith",
    "given": ["John"]
  }],
  "gender": "male",
  "birthDate": "1980-01-01"
}

4. Write JUnit Test

Create src/test/java/MyTest.java:

import org.fhirfrog.frog.api.TestScriptSource;
import org.fhirfrog.frog.internal.FhirTestExtension;
import org.junit.jupiter.api.TestTemplate;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(FhirTestExtension.class)
public class MyTest {

    @TestTemplate
    @TestScriptSource("fhir/patient-create.json")
    void testPatientCreate() {
        // Test logic is in the TestScript!
    }
}

5. Configure Server URL

Set the FHIR server URL (default: http://localhost:8080/fhir):

mvn test -Dfhir.server.url=http://localhost:8080/fhir

Or in your test:

@BeforeAll
static void setup() {
    System.setProperty("fhir.server.url", "http://localhost:8080/fhir");
}

6. Run Tests

mvn test

Output:

[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Using Testcontainers

For isolated testing with a containerized FHIR server:

@Testcontainers
@ExtendWith(FhirTestExtension.class)
public class MyTest {

    @Container
    private static final GenericContainer<?> hapi = 
        new GenericContainer<>("hapiproject/hapi:v7.6.0")
            .withExposedPorts(8080)
            .waitingFor(Wait.forHttp("/fhir/metadata"));

    @BeforeAll
    static void setup() {
        String url = "http://localhost:" + hapi.getMappedPort(8080) + "/fhir";
        System.setProperty("fhir.server.url", url);
    }

    @TestTemplate
    @TestScriptSource("fhir/patient-create.json")
    void testPatientCreate() {
    }
}

Next Steps

Common Issues

Server Not Running

Error: Connection refused

Solution: Ensure your FHIR server is running and accessible at the configured URL.

Fixture Not Found

Error: TestScript not found: fhir/patient-create.json

Solution: Ensure fixtures are in src/test/resources/fhir/ directory.

Variable Not Substituted

Error: Resource Patient/${patientId} not found

Solution: Ensure variable has sourceId pointing to the response that contains the value.

See Troubleshooting Guide for more help.