davinci_crd_test_kit 0.9.0

data/lib/davinci_crd_test_kit/client_tests/encounter_start_receive_request_test.rb

@@ -0,0 +1,68 @@
+require_relative '../urls'
+
+module DaVinciCRDTestKit
+  class EncounterStartReceiveRequestTest < Inferno::Test
+    include URLs
+
+    id :crd_encounter_start_request
+    title 'Request received for encounter-start hook'
+    description %(
+      This test waits for an incoming [encounter-start](https://hl7.org/fhir/us/davinci-crd/STU2/hooks.html#encounter-start)
+      hook request and responds to the client with the response types selected as an input.
+      )
+    receives_request :encounter_start
+
+    input :iss
+    input :encounter_start_selected_response_types,
+          title: 'Response types to return from encounter-start hook requests',
+          description: %(
+            Select the cards/action response types that the Inferno hook request endpoints will return. The default
+            response type that will be returned for this hook is the `Instructions` card type.
+          ),
+          type: 'checkbox',
+          default: ['instructions'],
+          options: {
+            list_options: [
+              {
+                label: 'External Reference',
+                value: 'external_reference'
+              },
+              {
+                label: 'Instructions',
+                value: 'instructions'
+              },
+              {
+                label: 'Coverage Information',
+                value: 'coverage_information'
+              },
+              {
+                label: 'Request Form Completion',
+                value: 'request_form_completion'
+              },
+              {
+                label: 'Create/Update Coverage Information',
+                value: 'create_update_coverage_info'
+              },
+              {
+                label: 'Launch SMART Application',
+                value: 'launch_smart_app'
+              }
+            ]
+          }
+
+    run do
+      wait(
+        identifier: "encounter-start #{iss}",
+        message: %(
+          **Encounter Start CDS Service Test**:
+
+          Invoke the encounter-start hook and send a request to:
+
+          `#{encounter_start_url}`
+
+          Inferno will process the request and return CDS cards if successful.
+        )
+      )
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/hook_request_optional_fields_test.rb

@@ -0,0 +1,41 @@
+require_relative '../client_hook_request_validation'
+
+module DaVinciCRDTestKit
+  class HookRequestOptionalFieldsTest < Inferno::Test
+    include DaVinciCRDTestKit::ClientHookRequestValidation
+
+    id :crd_hook_request_optional_fields
+    title 'Hook request contains optional fields'
+    description %(
+      Under the [CDS hooks HTTP Request section](https://cds-hooks.hl7.org/2.0/#http-request_1), the specification
+      requires that a CDS service request SHALL include a JSON POST body which MAY contain the following optional input
+      fields:
+        * `fhirServer` - *URL*
+        * `fhirAuthorization` - *object*
+        * `prefetch` - *object*
+
+      This test checks for the precense of these fields and if they are of the correct type. This test is optional and
+      will not fail if the hook request does not contain an optional field, it only produces an informational message.
+      If the client provides its FHIR server URL in the `fhirServer` field, and it's authorization token in the
+      `fhirAuthorization` field object, they will be produced as an output from this test to be used in
+      subsequent tests.
+    )
+    optional
+
+    output :client_fhir_server
+    output :client_access_token,
+           optional: true
+
+    uses_request :hook_request
+
+    run do
+      assert_valid_json(request.request_body)
+      request_body = JSON.parse(request.request_body)
+
+      client_fhir_server = hook_request_optional_fields_check(request_body)
+
+      output client_fhir_server: client_fhir_server[:fhir_server_uri],
+             client_access_token: client_fhir_server[:fhir_access_token]
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/hook_request_required_fields_test.rb

@@ -0,0 +1,40 @@
+require_relative '../client_hook_request_validation'
+
+module DaVinciCRDTestKit
+  class HookRequestRequiredFieldsTest < Inferno::Test
+    include DaVinciCRDTestKit::ClientHookRequestValidation
+    include URLs
+
+    id :crd_hook_request_required_fields
+    title 'Hook request contains required fields'
+    description %(
+      Under the [CDS hooks HTTP Request section](https://cds-hooks.hl7.org/2.0/#http-request_1), the specification
+      requires that a CDS service request SHALL include a JSON POST body with the following input fields:
+        * `hook` - *string*
+        * `hookInstance` - *string*
+        * `context` - *object*
+
+        Additionally, if the optional `fhirAuthorization` field is present, then the `fhirServer` field is required.
+
+        This test also checks that the `hook` field contains the correct CDS service name that the CDS client is sending
+        a request for
+    )
+
+    uses_request :hook_request
+
+    def hook_url
+      base_url + config.options[:hook_path]
+    end
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      assert_valid_json(request.request_body)
+      request_body = JSON.parse(request.request_body)
+
+      hook_request_required_fields_check(request_body, hook_name)
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/hook_request_valid_context_test.rb

@@ -0,0 +1,63 @@
+require_relative '../client_hook_request_validation'
+module DaVinciCRDTestKit
+  class HookRequestValidContextTest < Inferno::Test
+    include URLs
+    include ClientHookRequestValidation
+
+    id :crd_hook_request_valid_context
+    title 'Hook contains valid context'
+    description %(
+      As stated in the [CDS hooks specification](https://cds-hooks.hl7.org/2.0#http-request), a CDS service request's
+      `context` field contains hook-specific contextual data that the CDS service will need. The context is specified
+      in the hook definition to guide developers on the information available at the point in the workflow when the hook
+      is triggered.
+
+      The `context` requirements for each [hook specified in the CRD IG](https://hl7.org/fhir/us/davinci-crd/STU2/hooks.html)
+      can be found below:
+      * [appointment-book](https://cds-hooks.hl7.org/hooks/appointment-book/2023SepSTU1Ballot/appointment-book/)
+      * [encounter-start](https://cds-hooks.hl7.org/hooks/encounter-start/2023SepSTU1Ballot/encounter-start/)
+      * [encounter-discharge](https://cds-hooks.hl7.org/hooks/encounter-discharge/2023SepSTU1Ballot/encounter-discharge/)
+      * [order-select](https://cds-hooks.hl7.org/hooks/order-select/2023SepSTU1Ballot/order-select/)
+      * [order-dispatch](https://cds-hooks.hl7.org/hooks/order-dispatch/2023SepSTU1Ballot/order-dispatch/)
+      * [order-sign](https://cds-hooks.org/hooks/order-sign/)
+
+      This test performs the following:
+        * Verifies that the incoming hook request's `context` field contains the fields required by each hook and
+        that they are in the correct format
+        * Checks the optional fields and ensures they are in the correct format
+        * Validates any resources contained in a `context` field that contains a Bundle or FHIR resource
+        * Makes FHIR requests for any `context` fields that contain an id or reference and validates each resource
+        response against its corresponding CRD resource profile
+        * Check some specific `context` requirements for hooks that have special requirements for certain fields
+
+      The client must provide its FHIR server URL and access token in the hook request in order to run
+      this test.
+    )
+    uses_request :hook_request
+
+    input :client_fhir_server
+    input :client_access_token,
+          optional: true
+
+    fhir_client do
+      url :client_fhir_server
+      bearer_token :client_access_token
+    end
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      assert_valid_json(request.request_body)
+      request_body = JSON.parse(request.request_body)
+
+      hook_context = request_body['context']
+
+      assert(hook_context, 'Hook request does not contain required `context` field')
+
+      hook_request_context_check(hook_context, hook_name)
+      no_error_validation('Context is not valid.')
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/hook_request_valid_prefetch_test.rb

@@ -0,0 +1,151 @@
+require_relative '../urls'
+
+module DaVinciCRDTestKit
+  class HookRequestValidPrefetchTest < Inferno::Test
+    include URLs
+
+    id :crd_hook_request_valid_prefetch
+    title 'Hook contains valid prefetch response'
+    description %(
+      As stated in the [CDS hooks specification](https://cds-hooks.hl7.org/2.0#http-request), a CDS service request's
+      `prefetch` field is an optional field that contains key/value pairs of FHIR queries that the service is requesting
+      the CDS Client to perform and provide on each service call. The key is a string that describes the type of data
+      being requested and the value is a string representing the FHIR query. See [Prefetch Template](https://cds-hooks.hl7.org/2.0#prefetch-template)
+      for more information about how the `prefetch` formatting works.
+
+      This test verifies that the incoming hook request's `prefetch` field is in a valid JSON format and validates each
+      contained resource against its corresponding CRD resource profile. This test is optional and will be skipped if no
+      `prefetch` field is contained in the hook request.
+    )
+    optional
+
+    uses_request :hook_request
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    def cds_services_json
+      JSON.parse(File.read(File.join(
+                             __dir__, '..', 'routes', 'cds-services.json'
+                           )))['services']
+    end
+
+    def structure_definition_map
+      {
+        'Practitioner' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-practitioner',
+        'PractitionerRole' => 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitionerrole',
+        'Patient' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-patient',
+        'Coverage' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-coverage',
+        'RelatedPerson' => 'http://hl7.org/fhir/StructureDefinition/RelatedPerson',
+        'Encounter' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-encounter',
+        'DeviceRequest' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-devicerequest',
+        'MedicationRequest' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-medicationrequest',
+        'NutritionOrder' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-nutritionorder',
+        'ServiceRequest' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-servicerequest',
+        'VisionPrescription' => 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/profile-visionprescription'
+      }
+    end
+
+    def validate_prefetch_coverage(received_resource, advertised_prefetch_key,
+                                   received_context_patient_id, advertised_status)
+      assert_resource_type('Bundle', resource: received_resource)
+      assert(received_resource.entry.any?, 'Bundle of coverage resources received from prefetch is empty')
+      coverage_resource = received_resource.entry.first.resource
+      assert_resource_type('Coverage', resource: coverage_resource)
+      assert_valid_resource(resource: coverage_resource,
+                            profile_url: structure_definition_map['Coverage'])
+
+      coverage_beneficiary_reference = coverage_resource.beneficiary
+      coverage_beneficiary_patient_id = coverage_beneficiary_reference.reference_id
+      assert(coverage_beneficiary_patient_id.present?,
+             "Could not get beneficiary reference id from `#{advertised_prefetch_key}` field's Coverage resource")
+
+      assert(coverage_beneficiary_patient_id == received_context_patient_id,
+             %(Expected `#{advertised_prefetch_key}` field's Coverage resource to have a `beneficiary` reference id of
+             '#{received_context_patient_id}', instead was '#{coverage_beneficiary_patient_id}'))
+
+      coverage_status = coverage_resource.status
+      assert(coverage_status == advertised_status,
+             %(Expected `#{advertised_prefetch_key}` field's Coverage resource to have a `status` of
+             '#{advertised_status}', instead was '#{coverage_status}'))
+    end
+
+    def validate_prefetch_resource(received_resource, advertised_prefetch_key, context_field_resource_type,
+                                   context_field_id)
+      assert_resource_type(context_field_resource_type, resource: received_resource)
+
+      if hook_name == 'order-dispatch'
+        assert_valid_resource(resource: received_resource)
+      else
+        assert_valid_resource(resource: received_resource,
+                              profile_url: structure_definition_map[context_field_resource_type])
+      end
+
+      received_prefetch_resource_id = received_resource.id
+      assert(received_prefetch_resource_id.present?,
+             "`#{advertised_prefetch_key}` field's FHIR resource does not contain the `id` field")
+      assert(received_prefetch_resource_id == context_field_id,
+             %(Expected `#{advertised_prefetch_key}` field's FHIR resource to have an `id` of '#{context_field_id}',
+             instead was '#{received_prefetch_resource_id}'))
+    end
+
+    run do
+      assert_valid_json(request.request_body)
+      request_body = JSON.parse(request.request_body)
+
+      received_prefetch = request_body['prefetch']
+      received_context = request_body['context']
+
+      skip_if received_prefetch.blank?, 'Received hook request does not contain the `prefetch` field.'
+      skip_if received_context.blank?,
+              %(Received hook request does not contain the `context` field which is needed to validate the `prefetch`
+              field)
+
+      advertised_hook_service = cds_services_json.find { |service| service['hook'] == hook_name }
+
+      advertised_prefetch_fields = advertised_hook_service['prefetch']
+
+      advertised_prefetch_fields.each do |advertised_prefetch_key, advertised_prefetch_template|
+        next unless received_prefetch[advertised_prefetch_key].present?
+
+        assert(received_prefetch[advertised_prefetch_key].is_a?(Hash),
+               "Prefetch field `#{advertised_prefetch_key}` is not of type `Hash`.")
+
+        received_prefetch_resource = FHIR.from_contents(received_prefetch[advertised_prefetch_key].to_json)
+
+        if advertised_prefetch_template.include?('?')
+          advertised_prefetch_fhir_search = advertised_prefetch_template.gsub(/{|}/, '').split('?')
+          advertised_prefetch_resource_type = advertised_prefetch_fhir_search.first
+
+          if advertised_prefetch_resource_type == 'Coverage'
+            advertised_coverage_query_params = Rack::Utils.parse_nested_query(advertised_prefetch_fhir_search.last)
+
+            advertised_patient_token = advertised_coverage_query_params['patient']
+            advertised_context_patient_id_key = advertised_patient_token.split('.').last
+            received_context_patient_id = received_context[advertised_context_patient_id_key]
+
+            advertised_status_param = advertised_coverage_query_params['status']
+
+            validate_prefetch_coverage(received_prefetch_resource, advertised_prefetch_key, received_context_patient_id,
+                                       advertised_status_param)
+          end
+        else
+          advertised_prefetch_token = advertised_prefetch_template.gsub(/{|}/, '').split('/')
+          advertised_context_id = advertised_prefetch_token.last.split('.').last
+
+          if advertised_prefetch_token.length == 1
+            received_context_reference = FHIR::Reference.new(reference: received_context[advertised_context_id])
+            received_context_resource_type = received_context_reference.resource_type
+            received_context_id = received_context_reference.reference_id
+          else
+            received_context_id = received_context[advertised_context_id]
+            received_context_resource_type = advertised_prefetch_token.first
+          end
+          validate_prefetch_resource(received_prefetch_resource, advertised_prefetch_key,
+                                     received_context_resource_type, received_context_id)
+        end
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/order_dispatch_receive_request_test.rb

@@ -0,0 +1,79 @@
+require_relative '../urls'
+
+module DaVinciCRDTestKit
+  class OrderDispatchReceiveRequestTest < Inferno::Test
+    include URLs
+
+    id :crd_order_dispatch_request
+    title 'Request received for order-dispatch hook'
+    description %(
+        This test waits for an incoming [order-dispatch](https://hl7.org/fhir/us/davinci-crd/STU2/hooks.html#order-dispatch)
+        hook request and responds to the client with the response types selected as an input. This hook is a 'primary'
+        hook, meaning that CRD Servers SHALL, at minimum, return a [Coverage Information](https://hl7.org/fhir/us/davinci-crd/STU2/StructureDefinition-ext-coverage-information.html)
+        system action for these hooks, even if the response indicates that further information is needed or that the
+        level of detail provided is insufficient to determine coverage.
+      )
+    receives_request :order_dispatch
+
+    input :iss
+    input :order_dispatch_selected_response_types,
+          title: 'Response types to return from order-dispatch hook requests',
+          description: %(
+            Select the cards/action response types that the Inferno hook request endpoints will return. The default
+            response type that will be returned for this hook is the `Coverage Information` card type.
+          ),
+          type: 'checkbox',
+          default: ['coverage_information'],
+          options: {
+            list_options: [
+              {
+                label: 'External Reference',
+                value: 'external_reference'
+              },
+              {
+                label: 'Instructions',
+                value: 'instructions'
+              },
+              {
+                label: 'Coverage Information',
+                value: 'coverage_information'
+              },
+              {
+                label: 'Request Form Completion',
+                value: 'request_form_completion'
+              },
+              {
+                label: 'Create/Update Coverage Information',
+                value: 'create_update_coverage_info'
+              },
+              {
+                label: 'Launch SMART Application',
+                value: 'launch_smart_app'
+              },
+              {
+                label: 'Propose Alternate Request',
+                value: 'propose_alternate_request'
+              },
+              {
+                label: 'Additional Orders as Companions/Prerequisites',
+                value: 'companions_prerequisites'
+              }
+            ]
+          }
+
+    run do
+      wait(
+        identifier: "order-dispatch #{iss}",
+        message: %(
+          **Order Dispatch CDS Service Test**:
+
+          Invoke the order-dispatch hook and send a request to:
+
+          `#{order_dispatch_url}`
+
+          Inferno will process the request and return CDS cards if successful.
+        )
+      )
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/order_select_receive_request_test.rb

@@ -0,0 +1,76 @@
+require_relative '../urls'
+
+module DaVinciCRDTestKit
+  class OrderSelectReceiveRequestTest < Inferno::Test
+    include URLs
+
+    id :crd_order_select_request
+    title 'Request received for order-select hook'
+    description %(
+      This test waits for an incoming [order-select](https://hl7.org/fhir/us/davinci-crd/STU2/hooks.html#order-select)
+      hook request and responds to the client with the response types selected as an input.
+      )
+    receives_request :order_select
+
+    input :iss
+    input :order_select_selected_response_types,
+          title: 'Response types to return from order-select hook requests',
+          description: %(
+            Select the cards/action response types that the Inferno hook request endpoints will return. The default
+            response type that will be returned for this hook is the `Instructions` card type.
+          ),
+          type: 'checkbox',
+          default: ['instructions'],
+          options: {
+            list_options: [
+              {
+                label: 'External Reference',
+                value: 'external_reference'
+              },
+              {
+                label: 'Instructions',
+                value: 'instructions'
+              },
+              {
+                label: 'Coverage Information',
+                value: 'coverage_information'
+              },
+              {
+                label: 'Request Form Completion',
+                value: 'request_form_completion'
+              },
+              {
+                label: 'Create/Update Coverage Information',
+                value: 'create_update_coverage_info'
+              },
+              {
+                label: 'Launch SMART Application',
+                value: 'launch_smart_app'
+              },
+              {
+                label: 'Propose Alternate Request',
+                value: 'propose_alternate_request'
+              },
+              {
+                label: 'Additional Orders as Companions/Prerequisites',
+                value: 'companions_prerequisites'
+              }
+            ]
+          }
+
+    run do
+      wait(
+        identifier: "order-select #{iss}",
+        message: %(
+          **Order Select CDS Service Test**:
+
+          Invoke the order-select hook and send a request to:
+
+          `#{order_select_url}`
+
+          Inferno will process the request and return CDS cards if successful.
+        )
+      )
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/order_sign_receive_request_test.rb

@@ -0,0 +1,79 @@
+require_relative '../urls'
+
+module DaVinciCRDTestKit
+  class OrderSignReceiveRequestTest < Inferno::Test
+    include URLs
+
+    id :crd_order_sign_request
+    title 'Request received for order-sign hook'
+    description %(
+        This test waits for an incoming [order-sign](https://hl7.org/fhir/us/davinci-crd/STU2/hooks.html#order-sign)
+        hook request and responds to the client with the response types selected as an input. This hook is a 'primary'
+        hook, meaning that CRD Servers SHALL, at minimum, return a [Coverage Information](https://hl7.org/fhir/us/davinci-crd/STU2/StructureDefinition-ext-coverage-information.html)
+        system action for these hooks, even if the response indicates that further information is needed or that the
+        level of detail provided is insufficient to determine coverage.
+      )
+    receives_request :order_sign
+
+    input :iss
+    input :order_sign_selected_response_types,
+          title: 'Response types to return from order-sign hook requests',
+          description: %(
+            Select the cards/action response types that the Inferno hook request endpoints will return. The default
+            response type that will be returned for this hook is the `Coverage Information` card type.
+          ),
+          type: 'checkbox',
+          default: ['coverage_information'],
+          options: {
+            list_options: [
+              {
+                label: 'External Reference',
+                value: 'external_reference'
+              },
+              {
+                label: 'Instructions',
+                value: 'instructions'
+              },
+              {
+                label: 'Coverage Information',
+                value: 'coverage_information'
+              },
+              {
+                label: 'Request Form Completion',
+                value: 'request_form_completion'
+              },
+              {
+                label: 'Create/Update Coverage Information',
+                value: 'create_update_coverage_info'
+              },
+              {
+                label: 'Launch SMART Application',
+                value: 'launch_smart_app'
+              },
+              {
+                label: 'Propose Alternate Request',
+                value: 'propose_alternate_request'
+              },
+              {
+                label: 'Additional Orders as Companions/Prerequisites',
+                value: 'companions_prerequisites'
+              }
+            ]
+          }
+
+    run do
+      wait(
+        identifier: "order-sign #{iss}",
+        message: %(
+          **Order Sign CDS Service Test**:
+
+          Invoke the order-sign hook and send a request to:
+
+          `#{order_sign_url}`
+
+          Inferno will process the request and return CDS cards if successful.
+        )
+      )
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client_tests/retrieve_jwks_test.rb

@@ -0,0 +1,65 @@
+module DaVinciCRDTestKit
+  class RetrieveJWKSTest < Inferno::Test
+    id :crd_retrieve_jwks
+    title 'JWKS can be retrieved'
+    description %(
+        Verify that the JWKS can be retrieved from the JWKS uri if it is present in the `jku` field within the JWT token
+        header. As per the [CDS hooks specification](https://cds-hooks.hl7.org/2.0#trusting-cds-clients), if the jku
+        header field is ommitted, the CDS Client and CDS Service SHALL communicate the JWK Set out-of-band. Therefore,
+        if the client does not make their keys publicly available via a uri in the `jku` field, the user must
+        submit the jwk_set as an input to the test.
+      )
+
+    input :auth_token_header_json
+    input :jwk_set,
+          title: "The Client's JWK Set containing it's public key",
+          description: %(
+            Must supply if you do not make your keys publicly available via a uri in the authorization JWT header `jku`
+            field'
+          ),
+          type: 'textarea',
+          optional: true
+    output :crd_jwks_json, :crd_jwks_keys_json
+    makes_request :crd_client_jwks
+
+    run do
+      token_header = JSON.parse(auth_token_header_json)
+      jku = token_header['jku']
+
+      if jku.present?
+        get(jku, name: :crd_client_jwks)
+
+        assert_response_status(200)
+        assert_valid_json(response[:body])
+        output crd_jwks_json: response[:body]
+
+        jwks = JSON.parse(response[:body])
+      else
+        skip_if jwk_set.blank?,
+                %(JWK Set must be inputted if Client's JWK Set is not available via a URL identified by the jku header
+                field)
+
+        jwks = JSON.parse(jwk_set)
+      end
+
+      keys = jwks['keys']
+      assert keys.is_a?(Array), 'JWKS `keys` field must be an array'
+
+      assert keys.present?, 'The JWK set returned contains no public keys'
+
+      keys.each do |jwk|
+        JWT::JWK.import(jwk.deep_symbolize_keys)
+      rescue StandardError
+        assert false, "Invalid JWK: #{jwk.to_json}"
+      end
+
+      kid_presence = keys.all? { |key| key['kid'].present? }
+      assert kid_presence, '`kid` field must be present in each key if JWKS contains multiple keys'
+
+      kid_uniqueness = keys.map { |key| key['kid'] }.uniq.length == keys.length
+      assert kid_uniqueness, '`kid` must be unique within the client\' JWK Set.'
+
+      output crd_jwks_keys_json: keys.to_json
+    end
+  end
+end