davinci_crd_test_kit 0.9.0

data/lib/davinci_crd_test_kit/server_tests/launch_smart_app_card_validation_test.rb

@@ -0,0 +1,38 @@
+require_relative '../test_helper'
+
+module DaVinciCRDTestKit
+  class LaunchSmartAppCardValidationTest < Inferno::Test
+    include DaVinciCRDTestKit::TestHelper
+
+    title 'Valid Launch SMART Application cards received'
+    id :crd_launch_smart_app_card_validation
+    description %(
+      This test verifies the presence of valid Launch SMART Application cards within the list of valid cards
+      returned by the CRD service.
+      As per the [Da Vinci CRD Implementation Guide](https://hl7.org/fhir/us/davinci-crd/STU2/cards.html#launch-smart-application),
+      Launch SMART Application cards must contain links with the type set to `smart`.
+      This test checks for the presence of any Launch SMART Application cards by verifying:
+      - The existence of a `links` array within each card.
+      - That every link in the `links` array of a card is of type `smart`.
+
+      The test will be skipped if no Launch SMART Application cards are found within the returned valid cards.
+    )
+
+    optional
+    input :valid_cards_with_links
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      parsed_cards = parse_json(valid_cards_with_links)
+      external_reference_cards = parsed_cards.select do |card|
+        links = card['links']
+        links.present? && links.all? { |link| link['type'] == 'smart' }
+      end
+
+      skip_if external_reference_cards.blank?, "#{hook_name} hook response does not contain any Launch SMART App cards."
+    end
+  end
+end

data/lib/davinci_crd_test_kit/server_tests/propose_alternate_request_card_validation_test.rb

@@ -0,0 +1,65 @@
+require_relative '../test_helper'
+require_relative '../suggestion_actions_validation'
+
+module DaVinciCRDTestKit
+  class ProposeAlternateRequestCardValidationTest < Inferno::Test
+    include DaVinciCRDTestKit::TestHelper
+    include DaVinciCRDTestKit::SuggestionActionsValidation
+
+    title 'Valid Propose Alternate Request cards received'
+    id :crd_propose_alternate_request_card_validation
+    description %(
+      This test validates that all [Propose Alternate Request](https://hl7.org/fhir/us/davinci-crd/STU2/cards.html#propose-alternate-request)
+      cards received are valid. It checks for the presence of a card's suggestion
+      with a single action with `Action.type` of `update` or a card with at least
+      two actions, one with `Action.type` of `delete` and the other with
+      `Action.type` of `create`.
+    )
+    optional
+    input :valid_cards_with_suggestions, :contexts
+
+    EXPECTED_RESOURCE_TYPES = %w[
+      Device DeviceRequest Encounter Medication
+      MedicationRequest NutritionOrder ServiceRequest
+      VisionPrescription
+    ].freeze
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    def check_action_type(actions, action_type)
+      actions&.any? do |action|
+        action['type'] == action_type && action_resource_type_check(action, EXPECTED_RESOURCE_TYPES)
+      end
+    end
+
+    def propose_alternate_request_card?(card)
+      card['suggestions'].any? do |suggestion|
+        actions = suggestion['actions']
+        has_update = check_action_type(actions, 'update')
+        has_delete = check_action_type(actions, 'delete')
+        has_create = check_action_type(actions, 'create')
+
+        has_update || (has_delete && has_create)
+      end
+    end
+
+    run do
+      parsed_cards = parse_json(valid_cards_with_suggestions)
+      parsed_contexts = parse_json(contexts)
+      proposed_alternate_cards = parsed_cards.filter { |card| propose_alternate_request_card?(card) }
+
+      skip_if proposed_alternate_cards.blank?,
+              "#{hook_name} hook response does not contain a Propose Alternate Request card."
+
+      proposed_alternate_cards.each do |card|
+        card['suggestions'].each do |suggestion|
+          actions_check(suggestion['actions'], parsed_contexts)
+        end
+      end
+
+      no_error_validation('Some Proposed Alternate Request cards are not valid.')
+    end
+  end
+end

data/lib/davinci_crd_test_kit/server_tests/service_call_test.rb

@@ -0,0 +1,86 @@
+module DaVinciCRDTestKit
+  class ServiceCallTest < Inferno::Test
+    title 'Submit user-defined service requests'
+    id :crd_service_call_test
+    description %(
+      This test initiates POST request(s) to a specified CDS Service using the JSON body list provided by the user.
+      As indicated in the [CDS Hooks specification section on Calling a CDS Service](https://cds-hooks.hl7.org/2.0/#calling-a-cds-service),
+      the service endpoint is constructed by appending the individual service id to the CDS Service base URL,
+      following the format `{baseUrl}/cds-services/{service.id}`.
+
+      If running this group only, the user will need to provide the `service.id` to call the specified service.
+      Otherwise, the `service.id` is derived from the CDS Services that are retrieved through a query to the
+      discovery endpoint.
+
+      The test will be skipped if the CRD server does not host a CDS Service corresponding to the hook that
+      is being tested.
+
+      The test is deemed successful if the CRD server returns a 200 HTTP response for all requests.
+    )
+    input_order :base_url, :encryption_method, :jwks_kid
+    input :base_url, :service_ids
+    input :service_request_bodies,
+          optional: true,
+          type: 'textarea',
+          description: 'Provide a list of request bodies send multiple requests. e.g. [json_body_1, json_body_2]'
+    input :encryption_method,
+          title: 'JWT Signing Algorithm',
+          description: <<~DESCRIPTION,
+            CDS Hooks recommends ES384 and RS384 for JWT signature verification.
+            Select which method to use.
+          DESCRIPTION
+          type: 'radio',
+          options: {
+            list_options: [
+              {
+                label: 'ES384',
+                value: 'ES384'
+              },
+              {
+                label: 'RS384',
+                value: 'RS384'
+              }
+            ]
+          }
+    input :jwks_kid,
+          title: 'CDS Services JWKS kid',
+          description: <<~DESCRIPTION,
+            The key ID of the JWKS private key to use for signing the JWTs when invoking a CDS service endpoint
+            requiring authentication.
+            Defaults to the first JWK in the list if no kid is supplied.
+          DESCRIPTION
+          optional: true
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      discovery_url = "#{base_url.chomp('/')}/cds-services"
+      skip_if service_request_bodies.blank?,
+              'Request body not provided, skipping test.'
+      assert_valid_json(service_request_bodies)
+
+      payloads = [JSON.parse(service_request_bodies)].flatten
+      service_id = service_ids.split(', ').first.strip
+      service_endpoint = "#{discovery_url}/#{service_id}"
+      token = JwtHelper.build(
+        aud: service_endpoint,
+        iss: inferno_base_url,
+        jku: "#{inferno_base_url}/jwks.json",
+        kid: jwks_kid,
+        encryption_method:
+      )
+      headers = { 'Content-type' => 'application/json', 'Authorization' => "Bearer #{token}" }
+
+      payloads.each do |payload|
+        post(service_endpoint, body: payload.to_json, headers:, tags: [hook_name])
+      end
+
+      requests.each do |request|
+        assert_response_status(200, request:)
+        assert_valid_json(request.response_body)
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/server_tests/service_request_context_validation_test.rb

@@ -0,0 +1,30 @@
+require_relative '../server_hook_request_validation'
+require_relative '../test_helper'
+
+module DaVinciCRDTestKit
+  class ServiceRequestContextValidationTest < Inferno::Test
+    include DaVinciCRDTestKit::ServerHookRequestValidation
+    include DaVinciCRDTestKit::TestHelper
+
+    title 'All service requests contain valid context'
+    id :crd_service_request_context_validation
+    description %(
+      This test verifies that all service requests `context` field is valid and contains all the
+      required fields.
+    )
+    input :contexts
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      parsed_contexts = parse_json(contexts)
+      parsed_contexts.each do |context|
+        hook_request_context_check(context, hook_name)
+      end
+
+      no_error_validation('Some contexts are not valid.')
+    end
+  end
+end

data/lib/davinci_crd_test_kit/server_tests/service_request_optional_fields_validation_test.rb

@@ -0,0 +1,41 @@
+require_relative '../server_hook_request_validation'
+
+module DaVinciCRDTestKit
+  class ServiceRequestOptionalFieldsValidationTest < Inferno::Test
+    include DaVinciCRDTestKit::ServerHookRequestValidation
+
+    title 'All service requests contain optional fields'
+    id :crd_service_request_optional_fields_validation
+    description %(
+      This optional test reviews the user-submitted CRD service requests for the presence of optional fields:
+      `fhirAuthorization` and `prefetch`.
+
+      The test will not fail if these optional fields are missing from a service request; instead, it generates an
+      informational message.
+    )
+    optional
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      load_tagged_requests(hook_name)
+      skip_if requests.empty?, "No #{hook_name} request was made in a previous test as expected."
+
+      error_messages = []
+      requests.each_with_index do |request, index|
+        assert_valid_json(request.request_body)
+        request_body = JSON.parse(request.request_body)
+        hook_request_optional_fields_check(request_body)
+      rescue Inferno::Exceptions::AssertionException => e
+        error_messages << "Request #{index + 1}: #{e.message}"
+      end
+
+      error_messages.each do |msg|
+        messages << { type: 'error', message: msg }
+      end
+      assert error_messages.empty?, 'Some service requests have invalid optional fields.'
+    end
+  end
+end

data/lib/davinci_crd_test_kit/server_tests/service_request_required_fields_validation_test.rb

@@ -0,0 +1,43 @@
+require_relative '../server_hook_request_validation'
+module DaVinciCRDTestKit
+  class ServiceRequestRequiredFieldsValidationTest < Inferno::Test
+    include DaVinciCRDTestKit::ServerHookRequestValidation
+
+    title 'All service requests contain required fields'
+    id :crd_service_request_required_fields_validation
+    description %(
+      This test validates all CRD service requests provided by the user, ensuring each includes all required fields
+      specified in the [CDS Hooks spec section on Calling a CDS Service](https://cds-hooks.hl7.org/2.0/#calling-a-cds-service):
+      `hook`, `hookInstance`, and `context`. Furthermore, the test checks for the conditional presence of the
+      `fhirServer` field if `fhirAuthorization` is included.
+    )
+    output :contexts
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    run do
+      load_tagged_requests(hook_name)
+      skip_if requests.empty?, "No #{hook_name} request was made in a previous test as expected."
+
+      error_messages = []
+      contexts = []
+      requests.each_with_index do |request, index|
+        assert_valid_json(request.request_body)
+        request_body = JSON.parse(request.request_body)
+        contexts << request_body['context'] if request_body['context'].is_a?(Hash)
+        hook_request_required_fields_check(request_body, hook_name)
+      rescue Inferno::Exceptions::AssertionException => e
+        error_messages << "Request #{index + 1}: #{e.message}"
+      end
+
+      output contexts: contexts.to_json
+
+      error_messages.each do |msg|
+        messages << { type: 'error', message: msg }
+      end
+      assert error_messages.empty?, 'Some service requests made are not valid.'
+    end
+  end
+end

data/lib/davinci_crd_test_kit/server_tests/service_response_validation_test.rb

@@ -0,0 +1,82 @@
+require_relative '../cards_validation'
+
+module DaVinciCRDTestKit
+  class ServiceResponseValidationTest < Inferno::Test
+    include DaVinciCRDTestKit::CardsValidation
+
+    title 'All service responses contain valid cards and optional systemActions'
+    id :crd_service_response_validation
+    description %(
+      As per the [CDS Hooks spec section on CDS Service Response](https://cds-hooks.hl7.org/2.0/#cds-service-response),
+      a successful server's response to a service request must be a JSON object containing a `cards` array.
+      It must also contain a `systemActions` array for `appointment-book` and `order-sign` hook.
+
+      Each card must contain the following required fields: `summary`, `indicator`, and `source`.
+      The required fields must have a valid data structure.
+    )
+    output :valid_cards, :valid_system_actions
+
+    SYSTEM_ACTIONS_HOOK_NAMES = ['appointment-book', 'order-sign'].freeze
+
+    def hook_name
+      config.options[:hook_name]
+    end
+
+    def valid_cards
+      @valid_cards ||= []
+    end
+
+    def valid_system_actions
+      @valid_system_actions ||= []
+    end
+
+    def system_actions_check(system_actions)
+      system_actions.each do |action|
+        current_error_count = messages.count { |msg| msg[:type] == 'error' }
+        action_fields_validation(action)
+        valid_system_actions << action if current_error_count == messages.count { |msg| msg[:type] == 'error' }
+      end
+    end
+
+    def perform_system_actions_validation(system_actions, response_index)
+      if SYSTEM_ACTIONS_HOOK_NAMES.include?(hook_name) && system_actions.nil?
+        msg = "Server response #{response_index + 1} did not have `systemActions` field." \
+              "Must be present for #{hook_name}."
+        add_message('error', msg)
+      end
+      return if system_actions.nil?
+
+      unless system_actions.is_a?(Array)
+        add_message('error', "`systemActions` of server response #{response_index + 1} is not an array.")
+        return
+      end
+      system_actions_check(system_actions)
+    end
+
+    run do
+      load_tagged_requests(hook_name)
+      skip_if requests.blank?, "No #{hook_name} request was made in a previous test as expected."
+      successful_requests = requests.select { |request| request.status == 200 }
+      skip_if successful_requests.empty?, 'All service requests were unsuccessful.'
+
+      info do
+        unsuncessful_count = (requests - successful_requests).length
+        assert unsuncessful_count.zero?, "#{unsuncessful_count} out of #{requests.length} requests were unsuccessful"
+      end
+
+      successful_requests.each_with_index do |request, index|
+        service_response = JSON.parse(request.response_body)
+        perform_cards_validation(service_response['cards'], index)
+
+        perform_system_actions_validation(service_response['systemActions'], index)
+      rescue JSON::ParserError
+        add_message('error', "Invalid JSON: server response #{index + 1} is not a valid JSON.")
+      end
+
+      output valid_system_actions: valid_system_actions.to_json
+      output valid_cards: valid_cards.to_json
+
+      no_error_validation('Some service responses are not valid. Check messages for issues found.')
+    end
+  end
+end

data/lib/davinci_crd_test_kit/suggestion_actions_validation.rb

@@ -0,0 +1,123 @@
+require_relative 'server_hook_request_validation'
+module DaVinciCRDTestKit
+  module SuggestionActionsValidation
+    include DaVinciCRDTestKit::ServerHookRequestValidation
+
+    def action_required_fields
+      { 'type' => String, 'description' => String }
+    end
+
+    def action_fields_validation(action)
+      action_required_fields.each do |field, type|
+        validate_presence_and_type(action, field, type, 'Action')
+      end
+
+      action_type_field_validation(action)
+    end
+
+    def action_type_field_validation(action)
+      return unless action['type']
+
+      allowed_types = ['create', 'update', 'delete']
+      type = action['type']
+      unless allowed_types.include?(type)
+        error_msg = "Action type value `#{type}` is not allowed. Allowed values: #{allowed_types.to_sentence}. " \
+                    "In Action `#{action}`"
+        add_message('error', error_msg)
+        return
+      end
+
+      if ['create', 'update'].include?(type)
+        action_resource_field_validation(action, type)
+      else
+        action_resource_id_field_validation(action)
+      end
+    end
+
+    def action_resource_field_validation(action, type)
+      unless action['resource']
+        add_message('error', "`Action.resource` must be present for `#{type}` actions: `#{action}`.")
+        return
+      end
+
+      resource = FHIR.from_contents(action['resource'].to_json)
+      return if resource
+
+      add_message('error', "`Action.resource` must be a FHIR resource: `#{action}`.")
+    end
+
+    def action_resource_id_field_validation(action)
+      validate_presence_and_type(action, 'resourceId', Array, '`delete` Action')
+      return unless action['resourceId'].is_a?(Array)
+
+      action['resourceId'].each do |ref|
+        resource_reference_check(ref, 'Action.resourceId item')
+      end
+    end
+
+    def draft_orders_bundle_entry_refs(contexts)
+      @draft_orders_bundle_entry_refs ||= contexts.flat_map do |context|
+        draft_orders_bundle = parse_fhir_bundle_from_context('draftOrders', context)
+        draft_orders_bundle.entry.map { |entry| "#{entry.resource.resourceType}/#{entry.resource.id}" }
+      end
+    end
+
+    def action_resource_type_check(action, expected_resource_types)
+      resource_types = if ['create', 'update'].include?(action['type'])
+                         [FHIR.from_contents(action['resource'].to_json).resourceType]
+                       else
+                         action['resourceId'].map { |ref| ref.split('/').first }
+                       end
+      resource_types.all? { |resource_type| expected_resource_types.include?(resource_type) }
+    end
+
+    def extract_resource_types_by_action(actions, action_type)
+      actions.each_with_object([]) do |act, resource_types|
+        resource_types << act['resource']['resourceType'] if act['type'] == action_type
+      end
+    end
+
+    def actions_check(actions, contexts = nil)
+      create_actions_resource_types = extract_resource_types_by_action(actions, 'create')
+
+      actions.each do |action|
+        case action['type']
+        when 'create', 'update'
+          create_or_update_action_check(action, contexts)
+        when 'delete'
+          delete_action_check(action, create_actions_resource_types, contexts)
+        end
+      end
+    end
+
+    def create_or_update_action_check(action, contexts)
+      resource = FHIR.from_contents(action['resource'].to_json)
+      resource_is_valid?(resource:, profile_url: structure_definition_map[resource.resourceType])
+      return unless action['type'] == 'update' && contexts
+
+      ref = "#{resource.resourceType}/#{resource.id}"
+      return if draft_orders_bundle_entry_refs(contexts).include?(ref)
+
+      error_msg = "Resource being updated must be from the `draftOrders` entry. #{ref} is not in the " \
+                  "`context.drafOrders` of the submitted requests. In Action `#{action}`"
+      add_message('error', error_msg)
+    end
+
+    def delete_action_check(action, create_actions_resource_types, contexts)
+      action['resourceId'].each do |ref|
+        unless draft_orders_bundle_entry_refs(contexts).include?(ref)
+          error_msg = '`Action.resourceId` must reference FHIR resource from the `draftOrders` entry. ' \
+                      "#{ref} is not in `draftOrders`. In Action `#{action}`"
+          add_message('error', error_msg)
+          next
+        end
+
+        resource_type = ref.split('/').first
+        next if create_actions_resource_types.include?(resource_type)
+
+        error_msg = "There's no `create` action for the proposed order being deleted: `#{ref}`. In Action `#{action}`"
+        add_message('error', error_msg)
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/tags.rb

@@ -0,0 +1,8 @@
+module DaVinciCRDTestKit
+  APPOINTMENT_BOOK_TAG = 'crd_appointment_book'.freeze
+  ENCOUNTER_START_TAG = 'crd_encounter_start'.freeze
+  ENCOUNTER_DISCHARGE_TAG = 'crd_encounter_discharge'.freeze
+  ORDER_DISPATCH_TAG = 'crd_order_dispatch'.freeze
+  ORDER_SELECT_TAG = 'crd_order_select'.freeze
+  ORDER_SIGN_TAG = 'crd_order_sign'.freeze
+end

data/lib/davinci_crd_test_kit/test_helper.rb

@@ -0,0 +1,23 @@
+module DaVinciCRDTestKit
+  module TestHelper
+    def parse_json(input)
+      assert_valid_json(input)
+      JSON.parse(input)
+    end
+
+    def verify_at_least_one_test_passes(test_groups, id_pattern, error_message, id_exclude_pattern = nil)
+      runnables = test_groups.map do |group|
+        group.tests.find do |test|
+          test.id.include?(id_pattern) && (!id_exclude_pattern || !test.id.include?(id_exclude_pattern))
+        end
+      end.compact
+
+      results_repo = Inferno::Repositories::Results.new
+      results = results_repo.current_results_for_test_session_and_runnables(test_session_id, runnables)
+
+      pass_if(results.any? { |result| result.result == 'pass' })
+
+      skip error_message
+    end
+  end
+end

data/lib/davinci_crd_test_kit/urls.rb

@@ -0,0 +1,52 @@
+module DaVinciCRDTestKit
+  APPOINTMENT_BOOK_PATH = '/cds-services/appointment-book-service'.freeze
+  ENCOUNTER_START_PATH = '/cds-services/encounter-start-service'.freeze
+  ENCOUNTER_DISCHARGE_PATH = '/cds-services/encounter-discharge-service'.freeze
+  ORDER_DISPATCH_PATH = '/cds-services/order-dispatch-service'.freeze
+  ORDER_SELECT_PATH = '/cds-services/order-select-service'.freeze
+  ORDER_SIGN_PATH = '/cds-services/order-sign-service'.freeze
+  RESUME_PASS_PATH = '/resume_pass'.freeze
+  RESUME_FAIL_PATH = '/resume_fail'.freeze
+
+  module URLs
+    def base_url
+      @base_url ||= "#{Inferno::Application['base_url']}/custom/#{suite_id}"
+    end
+
+    def appointment_book_url
+      @appointment_book_url ||= base_url + APPOINTMENT_BOOK_PATH
+    end
+
+    def encounter_start_url
+      @encounter_start_url ||= base_url + ENCOUNTER_START_PATH
+    end
+
+    def encounter_discharge_url
+      @encounter_discharge_url ||= base_url + ENCOUNTER_DISCHARGE_PATH
+    end
+
+    def order_dispatch_url
+      @order_dispatch_url ||= base_url + ORDER_DISPATCH_PATH
+    end
+
+    def order_select_url
+      @order_select_url ||= base_url + ORDER_SELECT_PATH
+    end
+
+    def order_sign_url
+      @order_sign_url ||= base_url + ORDER_SIGN_PATH
+    end
+
+    def resume_pass_url
+      @resume_pass_url ||= base_url + RESUME_PASS_PATH
+    end
+
+    def resume_fail_url
+      @resume_fail_url ||= base_url + RESUME_FAIL_PATH
+    end
+
+    def suite_id
+      self.class.suite.id
+    end
+  end
+end

data/lib/davinci_crd_test_kit/version.rb

@@ -0,0 +1,3 @@
+module DaVinciCRDTestKit
+  VERSION = '0.9.0'.freeze
+end

data/lib/davinci_crd_test_kit.rb

@@ -0,0 +1,2 @@
+require_relative 'davinci_crd_test_kit/crd_server_suite'
+require_relative 'davinci_crd_test_kit/crd_client_suite'