TestPlan Overview

Experimental Feature

TestPlan support is currently experimental. The FHIR R5 TestPlan resource is still evolving, and some features may change. Use with caution in production environments.

TestPlans organize multiple TestScripts into test suites with dependencies and execution order. FHIR Frog dynamically expands TestPlans into JUnit tests.

What is a TestPlan?

A TestPlan is a FHIR resource that:

• Groups related TestScripts
• Defines execution dependencies
• Specifies test scope and objectives
• Enables recursive test suite composition
• Provides test organization and documentation

Basic Structure

{
  "resourceType": "TestPlan",
  "id": "patient-test-suite",
  "url": "http://example.org/TestPlan/patient-test-suite",
  "name": "PatientTestSuite",
  "title": "Patient API Test Suite",
  "status": "active",
  "testCase": [
    {
      "sequence": 1,
      "testRun": [
        {
          "narrative": "Test patient CRUD operations",
          "script": {
            "reference": "TestScript/patient-crud"
          }
        }
      ]
    },
    {
      "sequence": 2,
      "testRun": [
        {
          "narrative": "Test patient search",
          "script": {
            "reference": "TestScript/patient-search"
          }
        }
      ]
    }
  ]
}

TestPlan Execution

Test Dependencies

Sequential Execution

{
  "testCase": [
    {
      "sequence": 1,
      "testRun": [
        {
          "narrative": "Setup: Create test data",
          "script": {"reference": "TestScript/setup-data"}
        }
      ]
    },
    {
      "sequence": 2,
      "dependency": [
        {
          "predecessor": "TestScript/setup-data"
        }
      ],
      "testRun": [
        {
          "narrative": "Test: Query test data",
          "script": {"reference": "TestScript/query-data"}
        }
      ]
    }
  ]
}

Parallel Execution

Tests without dependencies run in parallel:

{
  "testCase": [
    {
      "testRun": [
        {"script": {"reference": "TestScript/patient-crud"}},
        {"script": {"reference": "TestScript/practitioner-crud"}},
        {"script": {"reference": "TestScript/organization-crud"}}
      ]
    }
  ]
}

Recursive TestPlans

TestPlans can reference other TestPlans:

{
  "resourceType": "TestPlan",
  "id": "au-core-suite",
  "title": "AU Core Complete Test Suite",
  "testCase": [
    {
      "testRun": [
        {
          "narrative": "Patient tests",
          "script": {"reference": "TestPlan/patient-suite"}
        },
        {
          "narrative": "Practitioner tests",
          "script": {"reference": "TestPlan/practitioner-suite"}
        }
      ]
    }
  ]
}

Cycle Detection

FHIR Frog detects circular dependencies:

JUnit Integration

TestPlans become dynamic JUnit tests:

@ExtendWith(FhirFrogExtension.class)
@TestPlan("TestPlan/au-core-suite")
class AUCoreTestSuite {
    // Tests dynamically generated from TestPlan
}

Generated test structure:

Test Scope

Define what's being tested:

{
  "testScope": [
    {
      "reference": "http://hl7.org.au/fhir/core/StructureDefinition/au-core-patient",
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/testscript-scope-phase-codes",
            "code": "unit"
          }
        ]
      }
    }
  ]
}

Test Objectives

Document test goals:

{
  "testObjective": [
    {
      "description": "Verify AU Core Patient profile conformance",
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/testscript-scope-conformance-codes",
            "code": "required"
          }
        ]
      }
    }
  ]
}

Real-World Example

AU Core test suite:

{
  "resourceType": "TestPlan",
  "id": "au-core-complete",
  "url": "http://hl7.org.au/fhir/core/TestPlan/au-core-complete",
  "name": "AUCoreCompleteTestSuite",
  "title": "AU Core Complete Test Suite",
  "status": "active",
  "description": "Comprehensive test suite for AU Core implementation",
  "testScope": [
    {
      "reference": "http://hl7.org.au/fhir/core/ImplementationGuide/hl7.fhir.au.core"
    }
  ],
  "testCase": [
    {
      "sequence": 1,
      "testRun": [
        {
          "narrative": "Patient CRUD with Medicare and IHI",
          "script": {"reference": "TestScript/au-core-patient-crud"}
        }
      ]
    },
    {
      "sequence": 2,
      "testRun": [
        {
          "narrative": "Practitioner CRUD with HPI-I and AHPRA",
          "script": {"reference": "TestScript/au-core-practitioner-crud"}
        }
      ]
    },
    {
      "sequence": 3,
      "testRun": [
        {
          "narrative": "Organization CRUD with HPI-O and ABN",
          "script": {"reference": "TestScript/au-core-organization-crud"}
        }
      ]
    },
    {
      "sequence": 4,
      "dependency": [
        {
          "predecessor": "TestScript/au-core-patient-crud"
        }
      ],
      "testRun": [
        {
          "narrative": "Observation with transaction bundle",
          "script": {"reference": "TestScript/au-core-observation-crud"}
        }
      ]
    },
    {
      "sequence": 5,
      "testRun": [
        {
          "narrative": "Advanced search scenarios",
          "script": {"reference": "TestScript/au-core-advanced-search"}
        }
      ]
    }
  ]
}

Benefits

1. Organization - Group related tests logically
2. Dependencies - Control execution order
3. Reusability - Compose test suites from smaller suites
4. Documentation - Self-documenting test structure
5. Reporting - Hierarchical test reports
6. CI/CD - Easy integration with build pipelines

Best Practices

1. Logical grouping - Group by resource type or feature
2. Minimal dependencies - Only when truly required
3. Clear narratives - Describe what each test does
4. Avoid deep nesting - Keep TestPlan hierarchy shallow
5. Test independence - Tests should not rely on shared state

Next Steps

• TestPlan Structure - Detailed structure reference
• Dependencies - Managing test dependencies
• Expansion - How TestPlans expand to JUnit tests
• Examples - Real-world TestPlans