TestScript — Executable FHIR integration test suite

The formal format for executable FHIR integration tests. Driven by HL7 Connectathons, consumed by Touchstone and Aegis Test Platform: every vendor runs the same suite.

Purpose of the resource

TestScript describes an integration-test suite that a test engine can execute against a FHIR server. Each test contains operations (HTTP GET/POST/PUT/DELETE, $-prefixed operation calls, transaction Bundles) and assertions (status code, content type, response body, HTTP header, FHIRPath value in the resource).

Key fields

JSON example

{
  "resourceType": "TestScript",
  "id": "example-patient-read",
  "url": "http://example.org/TestScript/patient-read",
  "version": "5.0.0",
  "name": "PatientReadTest",
  "title": "Patient Read Test",
  "status": "active",
  "experimental": false,
  "date": "2026-05-15",
  "test": [{
    "name": "Read Patient",
    "action": [{
      "operation": {
        "type": {
          "system": "http://terminology.hl7.org/CodeSystem/testscript-operation-codes",
          "code": "read"
        },
        "resource": "Patient",
        "encodeRequestUrl": true,
        "params": "/Patient/example"
      }
    }, {
      "assert": {
        "description": "Confirm 200 OK",
        "response": "okay"
      }
    }]
  }]
}

Touchstone and Connectathons

• Touchstone — FHIR test platform operated by Aegis, used as the official engine of HL7 Connectathons.
• Cardea — open-source tool used for ONC FHIR certification.
• HAPI Test Suite — JVM runner integrated in the HAPI FHIR base.
• IGs publish their TestScripts alongside their StructureDefinitions and ExampleScenarios.

Common pitfalls

• Assert without operator — default equals, rarely what you want for dates or IDs.
• Uninitialised variable — the test fails before the assertion.
• No teardown — the next run starts in a polluted state.

Related resources

• ExampleScenario.
• CapabilityStatement.
• ImplementationGuide.
• FHIR R5 hub.