FHIR Test Plan support

FHIR Test Plan Support

Table of Contents

• Introduction
• CREATE
  • TestPlan
  • Log File
• READ
  • TestPlan
  • Log File
• SEARCH
  • TestPlan
  • Log

The test client FHIR support includes transactions for CREATE, READ, and SEARCH operations. Here we show example TestPlans and log files.

Introduction

Much of the flexibility of the test client is in the Report/UseReport (Pub/Sub) model for sharing values between transaction executions. One thing that is new with the adaption of test client to FHIR is that FHIR has some standardized naming for the things we need to pass around using Report/UseReport.

As a reference, the HTML reference page of the FHIR spec can be handy.

FHIR defines the following concepts which we will use (some of these are slight extensions to the FHIR spec):

Base Address - The URL root of a FHIR server described as http(s)://server{/path}. In Toolkit FHIR simulators the base address has the format http://example.com:port/xdstools/fsim/billmysim where fsim is a fixed string and billmysim is the simulator id.

Type_ID - this is not specifically called out as a type in the spec, but the idea of identifying a resource instance by the combination of resource type and the ID within that type is prevalent in FHIR. Many FHIR examples reference Patient/1 which is the Patient resource with assigned ID of 1. This is the server independent name of a resource instance. (If you preface it with the Base Address it is then server specific). Within Toolkit source code this type is represented by the class FhirId.

Ref - FHIR talks frequently about a reference to a resource instance. This is the URL of an instance of a resource. Using the above definitions this is Base_Address + Type_ID. A typical example is http://example.com/fhir/Patient/1. This is the URL you can use in an HTTP GET to read the resource instance.

In the Report/UseReport documentation below, these terms are used. Specifically, the names (with examples) are:

• Base - address of a server - http://example.com/fhir

• Type_ID - combination of resource type and resource id - Patient/1

• Ref - reference to a resource instance - Base + Type_ID - http://example.com/fhir/Patient/1

• Url - the full URL used in the transaction

CREATE

The CREATE operation sends an instance of a single resource to a FHIR server resource manager which resides at Base + Type. Returned in the HTTP Location header is the URL of the resource instance created (Ref in the above type collection)

TestPlan

A FHIR CREATE testplan looks like

    <TestPlan>
      <Test>FhirTestClientCreate/create</Test>
      <TestStep id="create">
        <ExpectedStatus>Success</ExpectedStatus>
        <FhirCreateTransaction>
            <ResourceFile>patient.json</ResourceFile>
            <UrlExtension>/Patient</UrlExtension>
        </FhirCreateTransaction>
      </TestStep>
  </TestPlan>

• Test element - the value MUST be test-name/section-name

• FhirCreateTransaction - this runs the FHIR CREATE transaction

• ResourceFile - a JSON coded resource in the section directory (same directory as the testplan.xml file shown). The CREATE operation can only encode a single resource so there is only one file and it only contains a single resource. At the moment we only support JSON coding.

• UrlExtension - a slash ('/') followed by the resource type (Patient). The URL used in the CREATE will be Base + UrlExtension. The Base address will be extracted from the system configuration selected when this test is run.

Log File

log.xml looks like

<TestResults status="Pass">
   <Time>20170711134519.861</Time>
   <Site>bill__myfhirsys</Site>
   <Xdstest2_version/>
   <Xdstest2_args/>
   <testkit_version/>
   <Test>FhirTestClientCreate/create</Test>
   <TestStep id="create" status="Pass">
      <ExpectedStatus>Success</ExpectedStatus>
      <FhirCreateTransaction step="create">
         <ResourceFile>/Users/bill/git/iheos-toolkit2/it-tests/target/test-classes/war/toolkitx/testkit/tests/FhirTestClientCreate/create/patient.json</ResourceFile>
         <Endpoint>http://localhost:8889/xdstools2/fsim/bill__myfhirsys</Endpoint>
         <AssignedPatientId/>
         <AssignedUids/>
         <AssignedSourceId/>
         <Reports>
            <Report name="Base">http://localhost:8889/xdstools2/fsim/bill__myfhirsys</Report>
            <Report name="Url">http://localhost:8889/xdstools2/fsim/bill__myfhirsys/Patient</Report>
            <Report name="Type_ID">Patient/77653f43-35e7-4916-8aee-bb88a101c74c</Report>
            <Report name="Ref">http://localhost:8889/xdstools2/fsim/bill__myfhirsys/Patient/77653f43-35e7-4916-8aee-bb88a101c74c</Report>
         </Reports>
      </FhirCreateTransaction>
      <Assertions>
         <CompiledAssertion>[]</CompiledAssertion>
         <RawAssertionData>
            <Data/>
         </RawAssertionData>
         <AssertionCount>0</AssertionCount>
      </Assertions>
   </TestStep>
</TestResults>

• Report Base - server base address - also the URL the request was sent to (since this is a CREATE operation)

• Report Type_ID - the type and ID returned from the FHIR server (as part of the Location HTTP Header) - this is the ID that was assigned to the resource by the server.

• Report Ref - URL reference to the resource on the FHIR server. This is the value returned by the CREATE operation in the Location Header with the version information, if present, removed. This value can be used in an HTTP GET to retrieve the contents of the resource.

• Report Url - the URL that this transaction was sent to (same as Base since this was a CREATE operation)

READ

The FHIR READ operation passes the resource type and ID (Type_ID) and gets back the single resource or a 404 error.

TestPlan

A FHIR READ testplan looks like

<TestPlan>
    <Test>FhirTestClientCreate/read</Test>
    <TestStep id="read">
        <ExpectedStatus>Success</ExpectedStatus>
        <FhirReadTransaction>
            <UseReport test="FhirTestClientCreate" section="create" step="create" reportName="Ref" useAs="Ref"/>
        </FhirReadTransaction>
    </TestStep>
</TestPlan>

• Test element - the value MUST be test-name/section-name

• FhirReadTransaction - this runs the FHIR READ transaction

• UseReport - the test, section, step, reportName address the Report that is being referenced. ReportName will almost always have the value Ref since CREATE transactions automatically generate a Report of that name as a reference to the resource just created. The value of useAs will almost always be Ref since the FhirReadTransaction implementation is coded to expect it.

Log File

log.xml looks like

<TestResults status="Pass">
   <Time>20170711134521.141</Time>
   <Site>bill__myfhirsys</Site>
   <Xdstest2_version/>
   <Xdstest2_args/>
   <testkit_version/>
   <Test>FhirTestClientCreate/read</Test>
   <TestStep id="read" status="Pass">
      <ExpectedStatus>Success</ExpectedStatus>
      <FhirReadTransaction step="read">
         <Endpoint>http://localhost:8889/xdstools2/fsim/bill__myfhirsys</Endpoint>
         <UseReports>
            <UseReport test="FhirTestClientCreate"
                  section="create" step="create" reportName="Ref"
                  useAs="Ref" value="http://localhost:8889/xdstools2/fsim/bill__myfhirsys/Patient/50c105f4-de23-4f01-9102-eb35cad4466f"/>
         </UseReports>
         <AssignedPatientId/>
         <AssignedUids/>
         <AssignedSourceId/>
         <Result>FULL JSON CONTENT PLACED HERE - REMOVED FOR EXAMPLE</Result>
         <Reports>
            <Report name="Url">http://localhost:8889/xdstools2/fsim/bill__myfhirsys/Patient/50c105f4-de23-4f01-9102-eb35cad4466f</Report>
         </Reports>
      </FhirReadTransaction>
      <Assertions>
         <CompiledAssertion>[]</CompiledAssertion>
         <RawAssertionData>
            <Data/>
         </RawAssertionData>
         <AssertionCount>0</AssertionCount>
      </Assertions>
   </TestStep>
</TestResults>

• Report Ref - the URL used in the READ operation.

• Result - the full JSON representation returned. Here we have removed that content to make the rest of the example readable.

SEARCH

This is the generic FHIR query operation. The URL used is ${Base}/${ResourceType[}?name1=value1&name2=value2…​ A search returns a Bundle with zero or more resources inside it.

TestPlan

A FHIR SEARCH testplan looks like

<TestPlan>
    <Test>FhirTestClientCreate/query</Test>
    <TestStep id="query">
        <ExpectedStatus>Success</ExpectedStatus>
        <FhirSearchTransaction>
            <UseReport test="FhirTestClientCreate" section="create" step="create" reportName="Base" useAs="Base"/>
            <QueryParams>/Patient?family=Chalmers</QueryParams>
        </FhirSearchTransaction>
    </TestStep>
</TestPlan>

• Test element - the value MUST be test-name/section-name

• FhirSearchTransaction - this runs the FHIR SEARCH transaction

• UseReport - references a Report in an earlier test step by its test, section, name, and reportName. The reportName will almost always be Base since the CREATE transaction generates the Report with this name.

• QueryParams - the QueryParams value is appended to Base and the Resource Type to form the URL for the HTTP GET. According to the HTTP spec this must start with a question mark and it is always name=value pairs with an ampersand (&) separator.

Log

<TestResults status="Pass">
   <Time>20170711134521.402</Time>
   <Site>bill__myfhirsys</Site>
   <Xdstest2_version/>
   <Xdstest2_args/>
   <testkit_version/>
   <Test>FhirTestClientCreate/query</Test>
   <TestStep id="query" status="Pass">
      <ExpectedStatus>Success</ExpectedStatus>
      <FhirSearchTransaction step="query">
         <Endpoint>http://localhost:8889/xdstools2/fsim/bill__myfhirsys</Endpoint>
         <UseReports>
            <UseReport test="FhirTestClientCreate"
                  section="create" step="create" reportName="Url"
                  useAs="Url" value="http://localhost:8889/xdstools2/fsim/bill__myfhirsys/Patient"/>
         </UseReports>
         <AssignedPatientId/>
         <AssignedUids/>
         <AssignedSourceId/>
         <Result>Content removed </Result>
         <Reports>
            <Report name="Url">http://localhost:8889/xdstools2/fsim/bill__myfhirsys/Patient?family=Chalmers</Report>
         </Reports>
      </FhirSearchTransaction>
      <Assertions>
         <CompiledAssertion>[]</CompiledAssertion>
         <RawAssertionData>
            <Data/>
         </RawAssertionData>
         <AssertionCount>0</AssertionCount>
      </Assertions>
   </TestStep>
</TestResults>

• Report Url - the URL used in the query

• Result - JSON representation of the content returned - for the QUERY operation this will always be a (possibly empty) bundle unless an error is returned in a non-200 status code.