davinci_pas_test_kit 0.15.1 → 0.16.0

data/lib/davinci_pas_test_kit/client/abstract_subscription_update_delete_test.rb

@@ -0,0 +1,91 @@
+require_relative 'client_input_descriptions'
+require_relative 'session_identification'
+require_relative 'subscription_setup_requirement'
+
+module DaVinciPASTestKit
+  # abstract test, needs to be extended to include a version-specific URLs module
+  class AbstractSubscriptionUpdateDeleteTest < Inferno::Test
+    include SessionIdentification
+    include SubscriptionSetupRequirement
+
+    id :pas_client_subscription_update_delete_test
+    title 'PAS client submits Subscription update and deletion requests'
+    description %(
+      During this test, Inferno will wait for Subscription update and deletion requests
+      for the PAS Subscription created during the "Subscription Setup" group.
+
+      Additional notes:
+      - Updated Subscriptions must meet PAS Subscription requirements.
+      - Inferno will not send additional notifications or handshakes based on the updated Subscription.
+      - Inferno will modify the `Subscription.channel.payload` value on the updated Subscription to
+        `application/fhir+json` unless it is `application/json`.
+      - Inferno manages the `Subscription.status` value and will ignore requested changes to it, unless
+        the requested status is `off`.
+      - Inferno only accepts updates and deletes of the Subscription while this test is waiting.
+      - Each run of this test starts from the Subscription as created during the "Subscription Setup"
+        group. Changes made during earlier runs of this test, including deletion, are not carried over.
+    )
+
+    input :client_id,
+          title: 'Client Id',
+          type: 'text',
+          optional: true,
+          locked: true,
+          description: INPUT_CLIENT_ID_LOCKED
+    input :session_url_path,
+          title: 'Session-specific URL path extension',
+          type: 'text',
+          optional: true,
+          locked: true,
+          description: INPUT_SESSION_URL_PATH_LOCKED
+    output :confirmation_url
+
+    config options: { accepts_subscription_changes: true }
+
+    run do
+      subscription_id = require_created_subscription(skip_message: UPDATE_DELETE_SKIP_MESSAGE)['id']
+
+      wait_identifier = session_wait_identifier(client_id, session_url_path)
+      subscription_endpoint = session_endpoint_url(:subscription, client_id, session_url_path)
+      confirmation_url = "#{resume_pass_url}?token=#{wait_identifier}"
+      output(confirmation_url:)
+
+      wait(
+        identifier: wait_identifier,
+        message: <<~MESSAGE
+          **Subscription Update and Deletion Tests**:
+
+          Inferno will wait while the tester uses the PAS client to update and delete the PAS
+          Subscription created earlier in these tests. Updated Subscriptions must continue to meet
+          [Inferno](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Subscriptions-and-Notifications#subscription-validation)
+          and PAS Subscription requirements, but Inferno will not use the updated Subscription to deliver
+          notifications, including updated handshakes.
+
+          [Click here](#{confirmation_url}) when all requests have been submitted.
+
+          ### Endpoints
+
+          Submit [update](https://hl7.org/fhir/R4/http.html#update) (PUT) and
+          [delete](https://hl7.org/fhir/R4/http.html#delete) (DELETE) interaction
+          requests for the Subscription with id `#{subscription_id}` to:
+
+          `#{subscription_endpoint}/#{subscription_id}`
+
+          Inferno will also respond to [read](https://hl7.org/fhir/R4/http.html#read) (GET)
+          interactions and `$status` operation calls for this Subscription.
+
+          ### Authentication and Identification
+
+          #{auth_description_for_wait(client_id)}
+
+          ### Responses
+
+          The PAS Test Kit wiki contains details on the supported responses
+          that the PAS client can expect to receive during these tests:
+          - [Subscription update responses](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Subscriptions-and-Notifications#update-response)
+          - [Subscription deletion responses](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Subscriptions-and-Notifications#deletion-response)
+        MESSAGE
+      )
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/client_bundle_validation_helper.rb

@@ -0,0 +1,245 @@
+require_relative 'request_count_gating'
+
+module DaVinciPASTestKit
+  module ClientBundleValidationHelper
+    include RequestCountGating
+
+    ###########################################################################
+    # Tags and Request Loading
+    ###########################################################################
+    def request_type_tag
+      case operation_name
+      when 'inquire'
+        INQUIRE_TAG
+      when 'submit'
+        SUBMIT_TAG
+      else
+        raise Inferno::Exceptions::TestSuiteImplementationException.new(
+          'PAS Client Bundle Validation Test',
+          "invalid operation name #{operation_name}"
+        )
+      end
+    end
+
+    def workflow_tag
+      config.options[:workflow_tag]
+    end
+
+    # workflow_tag may be a single tag or an Array of tags; normalized to an Array so fetch_requests
+    # doesn't need its own is_a?(Array) check.
+    def workflow_tags
+      Array(workflow_tag)
+    end
+
+    def fetch_requests
+      tags = workflow_tags.presence || [nil]
+      tags.flat_map { |tag| load_tagged_requests(*[request_type_tag, tag].compact) }
+    end
+
+    ###########################################################################
+    # Request Count
+    ###########################################################################
+
+    # Raises if there are multiple requests and the test doesn't allow that.
+    # Skips if there are no requests and the test doesn't allow that.
+    # @param requests [Array<Inferno::Entities::Request>] the requests loaded for this test.
+    # @param description [String] identifies the requests in the raised message, e.g.
+    #   "submit requests".
+    def check_request_count(requests, description)
+      if requests.length > 1 && !multiple_requests_ok?
+        raise Inferno::Exceptions::TestSuiteImplementationException.new(
+          'multiple request handling',
+          "#{requests.length} #{description} were tagged for validation by this test, which does not expect " \
+          'more than one.'
+        )
+      elsif requests.empty?
+        if no_requests_ok?
+          pass "No #{description} analyzed."
+        else
+          skip "No #{description} received."
+        end
+      end
+    end
+
+    ###########################################################################
+    # Extraction logic
+    ###########################################################################
+
+    def message_contents(request)
+      case message_direction_name
+      when 'request'
+        request.request_body
+      when 'response'
+        request.response_body
+      else
+        raise Inferno::Exceptions::TestSuiteImplementationException.new(
+          'PAS Client Bundle Validation Test',
+          "invalid message direction name #{message_direction_name}"
+        )
+      end
+    end
+
+    def parameters_target_parameter_name
+      case message_direction_name
+      when 'request'
+        'resource'
+      when 'response'
+        'return'
+      else
+        raise Inferno::Exceptions::TestSuiteImplementationException.new(
+          'PAS Client Bundle Validation Test',
+          "invalid message direction name #{message_direction_name}"
+        )
+      end
+    end
+
+    ###########################################################################
+    # Validation logic
+    ###########################################################################
+
+    # Finds Bundles in the requests and determines which ones are non-conformant.
+    #
+    # Assumes this is the only thing logging to `messages` during this run and that it's
+    # called at most once, so every message present afterward is one it logged itself.
+    def non_conformant_bundles
+      requests = fetch_requests
+      check_request_count(requests, "$#{operation_name} #{message_direction_name}s")
+      requests.each_with_index { |request, index| validate_request(request, index) }
+
+      messages
+        .select { |message| message[:type] == 'error' }
+        .map { |message| message[:message].split(':', 2).first }
+        .uniq
+    end
+
+    # Validates one request/response, extracting and checking the Bundle(s) it contains and
+    # logging any problem found along the way - this only logs, callers determine what failed
+    # from `messages` afterward (see non_conformant_bundles).
+    def validate_request(request, index)
+      message_label = entity_label("#{message_direction_name.capitalize} #{index + 1}")
+      contents = message_contents(request)
+      message_resource = resource_from_message_contents(contents, message_label)
+      return if message_resource.blank?
+
+      # extraction varies - provided by test class if not using the default. May contain nil
+      # placeholders for positions that held something other than a Bundle (already reported),
+      # so Bundle labels keep their original position.
+      bundles = bundles_from_message_resource(message_resource, message_label)
+      parameters_has_errors?(message_resource, message_label) if response_parameters?(message_resource)
+      echoed_from = echo_source_bundle(request)
+
+      if bundles.length > 1
+        bundles.each_with_index do |bundle, bundle_index|
+          next if bundle.nil?
+
+          bundle_label = entity_label("#{message_label.delete_suffix(':')} Bundle #{bundle_index + 1}")
+          bundle_has_errors?(bundle, bundle_label, echoed_from)
+        end
+      else
+        bundles.compact.each { |bundle| bundle_has_errors?(bundle, message_label, echoed_from) }
+      end
+    end
+
+    # A label identifying one request/response, or a Bundle within one, for use as a message
+    # prefix. Always ends in ':' so a logged message's entity can be recovered by splitting on
+    # its first ':' - see non_conformant_bundles.
+    def entity_label(description)
+      "#{description}:"
+    end
+
+    def resource_from_message_contents(contents, label)
+      resource = FHIR.from_contents(contents)
+      messages << { type: 'error', message: "#{label} Not a FHIR resource." } unless resource.present?
+      resource
+    rescue StandardError
+      messages << { type: 'error', message: "#{label} Invalid JSON." }
+      nil
+    end
+
+    # standard Bundle extraction: 1 Bundle, not wrapped in Parameters
+    def bundles_from_message_resource(message_resource, message_label)
+      case message_resource
+      when FHIR::Bundle
+        [message_resource]
+      when FHIR::Parameters
+        messages << { type: 'error',
+                      message: "#{message_label} expected a Bundle resource, got Parameters." }
+        target_parameter_name = parameters_target_parameter_name
+        matching_resources = extract_resources_from_parameters(message_resource, target_parameter_name)
+
+        if matching_resources.empty?
+          messages << { type: 'error',
+                        message: "#{message_label} Parameters resource had no Bundle " \
+                                 "in a '#{target_parameter_name}' entry." }
+          []
+        elsif matching_resources.length > 1
+          messages << { type: 'error',
+                        message: "#{message_label} Parameters resource had multiple '#{target_parameter_name}' " \
+                                 'entries, but only one allowed (Bundles not validated).' }
+          []
+        elsif matching_resources.first.is_a?(FHIR::Bundle)
+          [matching_resources.first]
+        else
+          messages << { type: 'error',
+                        message: "#{message_label} Parameters resource '#{target_parameter_name}' entry expected to " \
+                                 "contain a Bundle, got #{matching_resources.first&.resourceType}" }
+          []
+        end
+
+      else
+        messages << { type: 'error',
+                      message: "#{message_label} expected a Bundle resource, got #{message_resource.resourceType}." }
+        []
+      end
+    end
+
+    # The request Bundle a response answers, so resources the response echoes back from it may keep
+    # the extensions they had in it - see PasBundleValidation#perform_no_custom_extensions_validation. Unwraps
+    # Parameters-wrapped requests (v2.2.1 $inquire). Nil when validating requests, or when the
+    # request has no Bundle.
+    def echo_source_bundle(request)
+      return unless message_direction_name == 'response'
+
+      request_resource = FHIR.from_contents(request.request_body)
+      if request_resource.is_a?(FHIR::Parameters)
+        request_resource = extract_resources_from_parameters(request_resource, 'resource').first
+      end
+      request_resource if request_resource.is_a?(FHIR::Bundle)
+    rescue StandardError
+      nil
+    end
+
+    # A Parameters wrapper Inferno sends around the response Bundles (v2.2.1 $inquire), which may be
+    # tester-provided, so it is checked for custom extensions too.
+    def response_parameters?(message_resource)
+      message_direction_name == 'response' && message_resource.is_a?(FHIR::Parameters)
+    end
+
+    def parameters_has_errors?(parameters, label)
+      parameters_messages = perform_no_custom_extensions_parameters_validation(parameters)
+      parameters_messages.each { |m| messages << { type: m[:type], message: "#{label} #{m[:message]}" } }
+      parameters_messages.any? { |m| m[:type] == 'error' }
+    rescue NoMethodError, TypeError, ArgumentError => e
+      messages << { type: 'error', message: "#{label} Parameters could not be validated: #{e.message}" }
+      true
+    end
+
+    def bundle_has_errors?(bundle, label, echoed_from = nil)
+      # Responses are sent by Inferno and may be tester-provided, so custom extensions aren't allowed.
+      bundle_messages =
+        if message_direction_name == 'response'
+          perform_no_custom_extensions_validation(bundle, operation_name, message_direction_name, ig_version,
+                                                  echoed_from:)
+        else
+          perform_bundle_validation(bundle, operation_name, message_direction_name, ig_version)
+        end
+      bundle_messages.each { |m| messages << { type: m[:type], message: "#{label} #{m[:message]}" } }
+      bundle_messages.any? { |m| m[:type] == 'error' }
+    rescue NoMethodError, TypeError, ArgumentError => e
+      # a malformed Bundle (e.g., an entry with no resource) shouldn't stop the remaining
+      # requests/Bundles from being validated
+      messages << { type: 'error', message: "#{label} could not be validated: #{e.message}" }
+      true
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/client_input_descriptions.rb

@@ -2,9 +2,104 @@
 
 module DaVinciPASTestKit
   INPUT_CLIENT_ID_LOCKED =
-    'The client\'s registered Client Id for use in obtaining access tokens. ' \
+    'The PAS client\'s registered Client Id for use in obtaining access tokens. ' \
     'Run the **1** Client Registration group to configure this input.'
   INPUT_SESSION_URL_PATH_LOCKED =
     'The additional path used to create session-specific endpoints. Run the ' \
     '**1** Client Registration group to configure this input.'
+
+  # Shared text for the "Demonstrate Must Support Coverage" group and its combined $submit/$inquire
+  # response_attest test, identical across PAS versions in each client/vX/pas_client_must_support_group.rb
+  # other than the requirement each version's attest test verifies.
+  MUST_SUPPORT_RECEIVE_GROUP_TITLE = 'Demonstrate Must Support Coverage'
+  MUST_SUPPORT_RECEIVE_GROUP_DESCRIPTION =
+    %(
+      During this group, Inferno will wait while the tester uses the PAS client to
+      make `$submit` and `$inquire` operation requests to Inferno demonstrating coverage
+      of must support elements not yet demonstrated.
+
+      Inferno then asks for confirmation that all responses were handled
+      without error and verifies the conformance of all requests and responses.
+    )
+  MUST_SUPPORT_SUBMIT_INQUIRE_ATTEST_TITLE =
+    'PAS client handled the $submit and $inquire responses without erroring'
+  MUST_SUPPORT_SUBMIT_INQUIRE_ATTEST_DESCRIPTION =
+    %(
+      During this test, the tester will verify that the PAS client handled
+      the `$submit` and `$inquire` operation responses, making the result available to
+      the user without failing or erroring.
+    )
+  MUST_SUPPORT_SUBMIT_INQUIRE_ATTEST_MESSAGE =
+    'I attest that the PAS client correctly handled the `$submit` and `$inquire` ' \
+    'operation responses received from Inferno during this test, making the details ' \
+    'available to users without errors.'
+
+  # Text for the v2.2.1 must support group, where the analysis is a separate group from the receive group
+  MUST_SUPPORT_COVERAGE_GROUP_TITLE = 'Must Support Coverage'
+  MUST_SUPPORT_COVERAGE_GROUP_DESCRIPTION =
+    %(
+      During this group, Inferno checks that the requests and responses exchanged during the
+      PAS scenario group and the most recent run of the "Demonstrate Must Support Coverage" group
+      include all required profiles and must support elements.
+
+      This group can be re-run on its own, for example after re-running another group, without
+      repeating the "Demonstrate Must Support Coverage" group or losing the requests made
+      during it.
+    )
+  MUST_SUPPORT_SEPARATE_GROUPS_DESCRIPTION =
+    <<~DESCRIPTION
+      The "Demonstrate Must Support Coverage" and "Must Support Coverage" groups can be run
+      separately. Re-running "Demonstrate Must Support Coverage" replaces the requests made during
+      its previous run, while "Must Support Coverage" can be re-run on its own to re-evaluate
+      coverage without making those requests again.
+    DESCRIPTION
+
+  def self.must_support_group_description(ig_version, wiki_anchor)
+    <<~DESCRIPTION
+      During these tests, Inferno will check that the PAS client demonstrates support for
+      all required profiles and must support elements. When looking for demonstration of
+      these profiles and elements, Inferno will consider requests and responses from
+      interactions performed during the PAS scenario group as well as additional ones
+      made when executing this group.
+
+      For additional details on these tests, what they check for, and the requirements
+      underlying them, see the ["Client Must Support Tests" section](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Must-Support)
+      of the Da Vinci PAS Test Kit wiki, specifically
+      - [Which messages Inferno considers when looking for demonstration of must support elements](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Must-Support#evaluated-messages).
+      - [What PAS clients must demonstrate to pass these #{ig_version} client must support tests](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Must-Support##{wiki_anchor}).
+    DESCRIPTION
+  end
+
+  def self.ms_responses_input_description(operation)
+    <<~DESCRIPTION
+      A JSON list of objects ([format](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#response-option-format))
+      that Inferno will use to respond to #{operation} requests during the
+      *Demonstrate Must Support Coverage* group. For each request, Inferno will
+      [select](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#response-option-evaluation)
+      and [instantiate](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#response-instantiation)
+      a response to return from this list. If no entries match or instantiation fails, Inferno will
+      [mock](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#mocked-responses)
+      a response.
+    DESCRIPTION
+  end
+
+  def self.user_response_input_description(operation, workflow, group_name)
+    timing_description = "during the *#{group_name}* group to indicate that the request has been #{workflow}"
+    user_response_input_description_base(operation, workflow, timing_description)
+  end
+
+  def self.user_response_input_description_for_update_tests(operation, default_decision, test_name)
+    timing_description = "during the *#{test_name}* test in the *Claim Updates* group"
+    user_response_input_description_base(operation, default_decision, timing_description)
+  end
+
+  def self.user_response_input_description_base(operation, workflow, timing_description)
+    <<~DESCRIPTION
+      If provided, this JSON will be [instantiated](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#response-instantiation)
+      and sent in response to the #{operation} request received #{timing_description}.
+      If not provided or if instantiation fails, Inferno will [mock](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#mocked-responses)
+      the response based on the submitted Claim and indicate it has been #{workflow}. In either
+      case, the response will be validated against the PAS Response Bundle profile.
+    DESCRIPTION
+  end
 end