davinci_crd_test_kit 0.12.2 → 0.14.0

data/lib/davinci_crd_test_kit/client/v2.0.1/invocation/order_sign_receive_request_test.rb

@@ -0,0 +1,136 @@
+require_relative '../client_urls'
+
+module DaVinciCRDTestKit
+  module V201
+    class OrderSignReceiveRequestTest < Inferno::Test
+      include ClientURLs
+
+      id :crd_v201_order_sign_request
+      title 'Request received for order-sign hook'
+      description %(
+        This test waits for multiple incoming [order-sign](https://hl7.org/fhir/us/davinci-crd/STU2/hooks.html#order-sign)
+        hook requests 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.
+
+        For more details on how Inferno's simulated CDS Service behave during hook invocation see the
+        [simulated CRD server](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Client-Details#crd-server-simulation)
+        documentation.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-crd_2.0.1@218', 'hl7.fhir.us.davinci-crd_2.0.1@225',
+                            'hl7.fhir.us.davinci-crd_2.0.1@243', 'hl7.fhir.us.davinci-crd_2.0.1@244',
+                            'hl7.fhir.us.davinci-crd_2.0.1@245', 'cds-hooks_2.0@15'
+
+      config options: { accepts_multiple_requests: true }
+
+      input :cds_jwt_iss,
+            title: 'CRD JWT Issuer',
+            description: %(
+              Value of the `iss` claim that must be sent on the Bearer token in the `Authorization`
+              header of all requests. Run or re-run the **Client Registration** group to set or
+              change this value.
+            ),
+            locked: true
+      input :order_sign_response_approach,
+            title: 'Response generation approach for order-sign',
+            description: %(
+              Determines how Inferno will generate response for order-sign
+              hook invocations.
+            ),
+            type: 'radio',
+            default: 'mocked',
+            options: {
+              list_options: [
+                {
+                  label: 'Create simple mocks based on selected response types',
+                  value: 'mocked'
+                },
+                {
+                  label: 'Generate responses based on a tester-provided template',
+                  value: 'custom'
+                }
+              ]
+            }
+      input :order_sign_selected_response_types,
+            title: 'Response types to return from order-sign hook requests',
+            description: %(
+              Select the CRD response types that the simulated Inferno CRD server will [mock](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses#mocked-responses)
+              when responding to hook invocations. If no types are selected, Inferno will mock and return
+              a [Coverage Information](https://hl7.org/fhir/us/davinci-crd/2.2.1/en/cards.html#coverage-information-response-type)
+              response for this primary hook.
+            ),
+            type: 'checkbox',
+            default: ['coverage_information', 'external_reference', 'instructions'],
+            optional: true,
+            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'
+                }
+              ]
+            },
+            enable_when: { input_name: 'order_sign_response_approach', value: 'mocked' }
+      input :order_sign_custom_response_template,
+            title: 'Custom response template for order-sign hook requests',
+            description: %(
+              Provide a [custom response template](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses#tester-directed-custom-responses)
+              in JSON form for Inferno to use when responding to hook invocations.
+            ),
+            type: 'textarea',
+            optional: true,
+            enable_when: { input_name: 'order_sign_response_approach', value: 'custom' }
+      output :continuation_url
+
+      run do
+        identifier = cds_jwt_iss
+        continuation_url = "#{resume_pass_url}?token=#{identifier}"
+        output(continuation_url:)
+
+        wait(
+          identifier:,
+          message: %(
+            **Order Sign CDS Service Test**:
+
+            Invoke the order-sign hook and send requests to:
+
+            `#{order_sign_url}`
+
+            Inferno will process the requests and return CDS cards if successful.
+
+            [Click here](#{continuation_url}) when you have finished submitting requests.
+          )
+        )
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/must_support/client_card_must_support_coverage_information.rb

@@ -0,0 +1,93 @@
+require_relative '../../../cross_suite/cards_identification'
+
+module DaVinciCRDTestKit
+  module V201
+    class ClientCardMustSupportCoverageInformationTest < Inferno::Test
+      include CardsIdentification
+
+      title 'Coverage Information Action Support'
+      id :crd_v201_client_card_must_support_coverage_information
+      description <<~DESCRIPTION
+        Checks that the client demonstrated support for the [Coverage Information](https://hl7.org/fhir/us/davinci-crd/2.2.1/en/cards.html#coverage-information-response-type)
+        action type. At least one hook invocation performed during this test session must have returned a Coverage Information action.
+        Additionally, all [coverage-information extension](https://hl7.org/fhir/us/davinci-crd/2.2.1/StructureDefinition-ext-coverage-information.html)
+        must support elements must be demonstrated across all the returned actions.
+
+        If this test fails, adjust the [cards returned by Inferno's simulated CRD server](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses)
+        and/or the hook requests made by the client during the Hooks tests such that Coverage Information actions are returned
+        that cover the full scope of the coverage-information extension](https://hl7.org/fhir/us/davinci-crd/2.2.1/StructureDefinition-ext-coverage-information.html)
+        and support for them is demonstrated.
+      DESCRIPTION
+
+      ALL_HOOKS = [
+        APPOINTMENT_BOOK_TAG,
+        ENCOUNTER_START_TAG,
+        ENCOUNTER_DISCHARGE_TAG,
+        ORDER_DISPATCH_TAG,
+        ORDER_SELECT_TAG,
+        ORDER_SIGN_TAG
+      ].freeze
+
+      def metadata
+        @metadata ||= YAML.load_file(
+          File.join(__dir__, '..', '..', '..', 'cross_suite', 'coverage-information_stu201_metadata.yml')
+        )
+      end
+
+      def configured_hook_name
+        config.options[:hook_name]
+      end
+
+      def crd_test_group
+        config.options[:crd_test_group]
+      end
+
+      def tags_to_load(hook_name)
+        crd_test_group.present? ? [hook_name, crd_test_group] : [hook_name]
+      end
+
+      def requests_to_analyze
+        if configured_hook_name.present?
+          load_requests_for_tags(tags_to_load(configured_hook_name))
+        else
+          ALL_HOOKS.each_with_object([]) do |hook_name, request_list|
+            request_list.concat(load_requests_for_tags(tags_to_load(hook_name)))
+          end
+        end
+      end
+
+      def load_requests_for_tags(tags_to_load)
+        load_tagged_requests(*tags_to_load)
+      end
+
+      class MustSupportMetadataHolder
+        attr_accessor :metadata
+
+        def initialize(metadata)
+          self.metadata = metadata
+        end
+
+        def must_supports
+          @must_supports ||= {
+            extensions: metadata[:must_supports][:extensions] || [],
+            slices: metadata[:must_supports][:slices] || [],
+            elements: metadata[:must_supports][:elements] || []
+          }
+        end
+      end
+
+      run do
+        loaded_requests = requests_to_analyze
+
+        sorted_cards = sorted_cards_from_requests(loaded_requests)
+
+        assert sorted_cards['actions'][COVERAGE_INFORMATION_RESPONSE_TYPE].present?,
+               'Coverage Information action support not demonstrated.'
+
+        coverage_information_extensions = extract_coverage_information_extensions(sorted_cards)
+        assert_must_support_elements_present(coverage_information_extensions, COVERAGE_INFO_EXT_URL,
+                                             metadata: MustSupportMetadataHolder.new(metadata))
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/must_support/client_card_must_support_external_reference.rb

@@ -0,0 +1,62 @@
+require_relative '../../../cross_suite/cards_identification'
+
+module DaVinciCRDTestKit
+  module V201
+    class ClientCardMustSupportExternalReferenceTest < Inferno::Test
+      include CardsIdentification
+
+      title 'External Reference Card Support'
+      id :crd_v201_client_card_must_support_external_reference
+      description <<~DESCRIPTION
+        Checks that the client demonstrated support for the [External Reference](https://hl7.org/fhir/us/davinci-crd/STU2/cards.html#external-reference)
+        card type. At least one hook invocation performed during this test session must have returned an External Reference card.
+
+        If this test fails, adjust the [cards returned by Inferno's simulated CRD server](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses)
+        and/or the hook requests made by the client during the Hooks tests such that an External Reference card is returned and support for it is demonstrated.
+      DESCRIPTION
+
+      ALL_HOOKS = [
+        APPOINTMENT_BOOK_TAG,
+        ENCOUNTER_START_TAG,
+        ENCOUNTER_DISCHARGE_TAG,
+        ORDER_DISPATCH_TAG,
+        ORDER_SELECT_TAG,
+        ORDER_SIGN_TAG
+      ].freeze
+
+      def configured_hook_name
+        config.options[:hook_name]
+      end
+
+      def crd_test_group
+        config.options[:crd_test_group]
+      end
+
+      def tags_to_load(hook_name)
+        crd_test_group.present? ? [hook_name, crd_test_group] : [hook_name]
+      end
+
+      def requests_to_analyze
+        if configured_hook_name.present?
+          load_requests_for_tags(tags_to_load(configured_hook_name))
+        else
+          ALL_HOOKS.each_with_object([]) do |hook_name, request_list|
+            request_list.concat(load_requests_for_tags(tags_to_load(hook_name)))
+          end
+        end
+      end
+
+      def load_requests_for_tags(tags_to_load)
+        load_tagged_requests(*tags_to_load)
+      end
+
+      run do
+        loaded_requests = requests_to_analyze
+        sorted_cards = sorted_cards_from_requests(loaded_requests)
+
+        assert sorted_cards['cards'][EXTERNAL_REFERENCE_RESPONSE_TYPE].present?,
+               'External Reference card support not demonstrated.'
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/must_support/client_card_must_support_instructions.rb

@@ -0,0 +1,62 @@
+require_relative '../../../cross_suite/cards_identification'
+
+module DaVinciCRDTestKit
+  module V201
+    class ClientCardMustSupportInstructionsTest < Inferno::Test
+      include CardsIdentification
+
+      title 'Instructions Card Support'
+      id :crd_v201_client_card_must_support_instructions
+      description <<~DESCRIPTION
+        Checks that the client demonstrated support for the [Instructions](https://hl7.org/fhir/us/davinci-crd/STU2/cards.html#external-reference)
+        card type. At least one hook invocation performed during this test session must have returned an Instructions card.
+
+        If this test fails, adjust the [cards returned by Inferno's simulated CRD server](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses)
+        and/or the hook requests made by the client during the Hooks tests such that an Instructions card is returned and support for it is demonstrated.
+      DESCRIPTION
+
+      ALL_HOOKS = [
+        APPOINTMENT_BOOK_TAG,
+        ENCOUNTER_START_TAG,
+        ENCOUNTER_DISCHARGE_TAG,
+        ORDER_DISPATCH_TAG,
+        ORDER_SELECT_TAG,
+        ORDER_SIGN_TAG
+      ].freeze
+
+      def configured_hook_name
+        config.options[:hook_name]
+      end
+
+      def crd_test_group
+        config.options[:crd_test_group]
+      end
+
+      def tags_to_load(hook_name)
+        crd_test_group.present? ? [hook_name, crd_test_group] : [hook_name]
+      end
+
+      def requests_to_analyze
+        if configured_hook_name.present?
+          load_requests_for_tags(tags_to_load(configured_hook_name))
+        else
+          ALL_HOOKS.each_with_object([]) do |hook_name, request_list|
+            request_list.concat(load_requests_for_tags(tags_to_load(hook_name)))
+          end
+        end
+      end
+
+      def load_requests_for_tags(tags_to_load)
+        load_tagged_requests(*tags_to_load)
+      end
+
+      run do
+        loaded_requests = requests_to_analyze
+        sorted_cards = sorted_cards_from_requests(loaded_requests)
+
+        assert sorted_cards['cards'][INSTRUCTIONS_RESPONSE_TYPE].present?,
+               'Instructions card support not demonstrated.'
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/registration/client_registration_verification_test.rb

@@ -0,0 +1,94 @@
+require 'jwt'
+
+module DaVinciCRDTestKit
+  module V201
+    class CRDClientRegistrationVerification < Inferno::Test
+      include ClientURLs
+
+      id :crd_v201_client_registration_verification
+      title 'Verify CRD Client Registration'
+      description %(
+        During this test, Inferno will verify that the CRD client registration details
+        provided are conformant.
+      )
+
+      verifies_requirements 'cds-hooks_2.0@174', 'cds-hooks_2.0@197'
+
+      input :cds_jwt_iss,
+            title: 'CRD JWT Issuer',
+            description: %(
+              The `iss` claim of the JWT in the Authorization header sent by the CRD client under test on
+              all CRD requests. This value will be used to associate incoming requests with this test
+              session and any requests that use a different `iss` value will not be recognized.
+            ),
+            type: 'text'
+      input :cds_jwk_set,
+            title: 'CRD JSON Web Key Set (JWKS)',
+            type: 'textarea',
+            description: %(
+              The CRD client's JWK Set containing it's public key. May be either
+              a publicly accessible url containing the JWKS, or the raw JWKS.
+              The client suite may be run without this input, but it is required
+              for the tests to pass.
+            ),
+            optional: true
+
+      run do
+        assert cds_jwk_set.present?, 'Provide a jwk set in the **CRD JSON Web Key Set (JWKS)** input.'
+
+        jwks_warnings = []
+        parsed_jwk_set = jwk_set(cds_jwk_set, jwks_warnings)
+        jwks_warnings.each { |warning| add_message('warning', warning) }
+
+        assert parsed_jwk_set.length.positive?, 'JWKS content does not include any valid keys.'
+
+        assert messages.none? { |msg| msg[:type] == 'error' }, 'Invalid key set provided. See Messages for details.'
+      end
+
+      def jwk_set(jku, warning_messages = []) # rubocop:disable Metrics/CyclomaticComplexity
+        jwk_set = JWT::JWK::Set.new
+
+        if jku.blank?
+          warning_messages << 'No key set input.'
+          return jwk_set
+        end
+
+        jwk_body = # try as raw jwk set
+          begin
+            JSON.parse(jku)
+          rescue JSON::ParserError
+            nil
+          end
+
+        if jwk_body.blank?
+          retrieved = Faraday.get(jku) # try as url pointing to a jwk set
+          jwk_body =
+            begin
+              JSON.parse(retrieved.body)
+            rescue JSON::ParserError
+              warning_messages << "Failed to fetch valid json from jwks uri #{jku}."
+              nil
+            end
+        else
+          warning_messages << 'Providing the JWK Set directly is strongly discouraged.'
+        end
+
+        return jwk_set if jwk_body.blank?
+
+        jwk_body['keys']&.each_with_index do |key_hash, index|
+          parsed_key =
+            begin
+              JWT::JWK.new(key_hash)
+            rescue JWT::JWKError => e
+              id = key_hash['kid'] | index
+              warning_messages << "Key #{id} invalid: #{e}"
+              nil
+            end
+          jwk_set << parsed_key unless parsed_key.blank?
+        end
+
+        jwk_set
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/registration/client_service_registration_attestation_test.rb

@@ -0,0 +1,40 @@
+module DaVinciCRDTestKit
+  module V201
+    class CRDClientServiceRegistrationAttestation < Inferno::Test
+      include ClientURLs
+
+      id :crd_v201_client_service_registration_attestation
+      title 'Attest to the registration of the Inferno Service by the CRD client'
+      description %(
+        During this test, the tester will confirm that Inferno has been registered as a
+        trusted CRD server that can access the CRD client's FHIR Server.
+      )
+
+      verifies_requirements 'cds-hooks_2.0@174'
+
+      output :attest_true_url
+      output :attest_false_url
+
+      run do
+        identifier = SecureRandom.hex(32)
+        attest_true_url = "#{resume_pass_url}?token=#{identifier}"
+        attest_false_url = "#{resume_fail_url}?token=#{identifier}"
+        output(attest_true_url:)
+        output(attest_false_url:)
+        wait(
+          identifier:,
+          message: <<~MESSAGE
+            **Registration of Inferno as a trusted CRD server**:
+
+            I attest that Inferno has been registered as a trusted CRD server that is allowed to access
+            data stored on the CRD client's FHIR Server.
+
+            [Click here](#{attest_true_url}) if the above statement is **true**.
+
+            [Click here](#{attest_false_url}) if the above statement is **false**.
+          MESSAGE
+        )
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/verify_request/hook_request_fetched_data_test.rb

@@ -0,0 +1,86 @@
+require_relative '../../../cross_suite/tags'
+
+module DaVinciCRDTestKit
+  module V201
+    class HookRequestFetchedDataTest < Inferno::Test
+      id :crd_v201_hook_request_fetched_data
+      title 'Minimum resource dataset was accessible during the hook invocation'
+      description %(
+        Clients must make a set of data related to the request available to the CRD server via either prefetch
+        as a part of the hook invocation or via FHIR API during server processing of the hook call. According
+        to the IG, the minimal data set includes:
+        - Patient
+        - Relevant Coverage
+        - Authoring Practitioner
+        - Authoring Organization
+        - Requested performing Practitioner (if specified)
+        - Requested performing Organization (if specified)
+        - Requested Location (if specified)
+        - Associated Medication (if any)
+        - Associated Device (if any)
+
+        When it receives a hook invocation, Inferno analyzes the hook request to determine what resources it
+        needs access to and requests those that are not provided as a part of the prefetched data. All data
+        is requested via the read interaction except for Coverages which requires a search interaction.
+
+        This test checks that those requests were successful, demonstrating that the system can provide access
+        to this required information.
+
+        For more details on what Inferno's simulated CDS Service fetches during hook invocation and
+        how the client must respond to pass this test, see the
+        [Data Fetching During Hook Invocations](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Client-Details#data-fetching-during-hook-invocations)
+        documentation.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-crd_2.0.1@43', 'hl7.fhir.us.davinci-crd_2.0.1@323'
+
+      def hook_name
+        config.options[:hook_name]
+      end
+
+      def crd_test_group
+        config.options[:crd_test_group]
+      end
+
+      def tags_to_load
+        crd_test_group.present? ? [hook_name, crd_test_group] : [hook_name]
+      end
+
+      def no_error_validation(message)
+        assert messages.none? { |msg| msg[:type] == 'error' }, message
+      end
+
+      run do
+        hook_requests = load_tagged_requests(*tags_to_load)
+
+        hook_requests.each do |hook_request|
+          request_body = JSON.parse(hook_request.request_body)
+          hook_instance = request_body['hookInstance']
+
+          if request_body.dig('fhirAuthorization', 'access_token').blank?
+            add_message(:error, "Access token not provided for FHIR data access on hook instance `#{hook_instance}`.")
+          end
+
+          failed_data_fetches =
+            load_tagged_requests(TagMethods.hook_instance_data_fetch_tag(hook_instance)).reject do |fetch|
+              fetch.status.to_s.starts_with?('2')
+            end
+
+          next unless failed_data_fetches.present?
+
+          server = "#{request_body['fhirServer'].chomp('/')}/"
+          failed_data_fetches.each do |request|
+            reference = request.url.starts_with?(server) ? request.url[server.length..] : request.url
+            if reference.starts_with?('Coverage')
+              add_message(:error,
+                          "Failed to perform Coverage search `#{reference}` for hook instance `#{hook_instance}`.")
+            else
+              add_message(:error, "Failed to read reference `#{reference}` for hook instance `#{hook_instance}`.")
+            end
+          end
+        end
+
+        no_error_validation('Inferno could not fetch some required data during the hook invocations.')
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.0.1/verify_request/hook_request_optional_fields_test.rb

@@ -0,0 +1,63 @@
+require_relative '../../client_hook_request_validation'
+require_relative '../client_urls'
+
+module DaVinciCRDTestKit
+  module V201
+    class HookRequestOptionalFieldsTest < Inferno::Test
+      include ClientHookRequestValidation
+      include ClientURLs
+
+      id :crd_v201_hook_request_optional_fields
+      title 'Hook request optional fields are valid'
+      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 that the optional fields that are present are of the correct type. This test
+        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.
+      )
+
+      verifies_requirements 'cds-hooks_2.0@1', 'cds-hooks_2.0@3', 'cds-hooks_2.0@20', 'cds-hooks_2.0@21',
+                            'cds-hooks_2.0@23', 'cds-hooks_2.0@65', 'cds-hooks_2.0@66', 'cds-hooks_2.0@67',
+                            'cds-hooks_2.0@68', 'cds-hooks_2.0@69', 'cds-hooks_2.0@70'
+
+      def hook_name
+        config.options[:hook_name]
+      end
+
+      output :client_fhir_server
+      output :client_access_token,
+             optional: true
+
+      run do
+        load_tagged_requests(hook_name)
+        skip_if requests.empty?, "No #{hook_name} requests were made in a previous test as expected."
+        client_fhir_server = nil
+        requests.each_with_index do |request, index|
+          @request_number = index + 1
+          request_body = json_parse(request.request_body)
+          if request_body.blank?
+            add_message('error', "#{request_number}Hook request body cannot be empty.")
+            next
+          end
+
+          fhir_server_info = hook_request_optional_fields_check(request_body, ig_version: 'v201')
+          client_fhir_server ||= fhir_server_info
+        end
+
+        unless client_fhir_server.nil?
+          output client_fhir_server: client_fhir_server[:fhir_server_uri],
+                 client_access_token: client_fhir_server[:fhir_access_token]
+        end
+        no_error_validation('Some service requests contain invalid optional fields.')
+      end
+    end
+  end
+end