davinci_pas_test_kit 0.14.0 → 0.15.0

data/lib/davinci_pas_test_kit/client/v2.2.1/workflows/pas_client_claim_update_changed_entries_test.rb

@@ -0,0 +1,100 @@
+require_relative 'pas_client_claim_update_validation_utils'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    # spec-71 and spec-72
+    class PASClientClaimUpdateChangedEntriesTest < Inferno::Test
+      include ClaimUpdateValidationUtils
+
+      id :pas_client_v221_claim_update_changed_entries_test
+      title 'Added, modified, or canceled entries carry an infoChanged extension with the correct valueCode'
+      description %(
+        The PAS IG requires that entries added, modified, or canceled compared to the immediately prior version
+        of the Claim referenced in `Claim.related.claim`
+        [contain an infoChanged extension](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/conformancedetails.html#ci-c-spec-71)
+        within the `Claim.item` or `Claim.supportingInfo` element, and that the
+        [infoChanged valueCode](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/conformancedetails.html#ci-c-spec-72)
+        distinguishes added entries from modified or canceled entries.
+
+        The bound [PAS Information Change Mode value set](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/ValueSet-PASInformationChangeMode.html)
+        defines exactly two codes: `added` ("new information that was not sent previously") and `changed`
+        ("previously sent information has been changed"). This test compares each detail-bearing Claim Update
+        against the immediately prior Claim, classifies each entry as added/modified/canceled (comparing content
+        while ignoring the change-tracking extensions), and confirms that each changed entry carries an
+        infoChanged extension whose valueCode is valid and matches its change type - `added` for newly added
+        entries and `changed` for modified or canceled entries.
+
+        **Note:** the spec-72 conformance text states added entries use `changed`, which conflicts with the
+        value set's definition of `added`; this test follows the value set definitions.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-71',
+                            'hl7.fhir.us.davinci-pas_2.2.1@spec-72',
+                            'hl7.fhir.us.davinci-pas_2.2.1@prof-9',
+                            'hl7.fhir.us.davinci-pas_2.2.1@prof-10'
+
+      run do
+        comparisons = claim_update_detail_comparisons
+        skip_if comparisons.empty?,
+                'Not enough consecutive Claim Update requests were received to verify change marking.'
+
+        comparisons.each do |comparison|
+          check_changed_entries_marked(comparison[:current].item, comparison[:prior].item, 'item', comparison)
+          check_changed_entries_marked(comparison[:current].supportingInfo, comparison[:prior].supportingInfo,
+                                       'supportingInfo', comparison)
+        end
+
+        assert_no_error_messages('One or more changed entries were missing an infoChanged extension or used an ' \
+                                 'incorrect valueCode. See Messages for details.')
+      end
+
+      def check_changed_entries_marked(current_entries, prior_entries, kind, comparison)
+        prior_by_sequence = index_by_sequence(prior_entries)
+
+        Array(current_entries).each do |entry|
+          prior_entry = prior_by_sequence[entry.sequence]
+          change_type =
+            if prior_entry.nil?
+              'added'
+            elsif newly_cancelled?(entry, prior_entry)
+              'canceled'
+            elsif entry_modified?(entry, prior_entry)
+              'modified'
+            end
+          next if change_type.nil?
+
+          extension = info_changed_extension(entry)
+          if extension.nil?
+            add_message('error',
+                        "The #{change_type} #{kind} (sequence #{entry.sequence}) in the " \
+                        "#{comparison[:current_label]} must contain an infoChanged extension (it changed " \
+                        "relative to the #{comparison[:prior_label]}).")
+            next
+          end
+
+          check_info_changed_code(extension.valueCode, change_type, kind, entry, comparison)
+        end
+      end
+
+      # Newly added entries SHALL use `added`; modified or canceled entries SHALL use `changed`.
+      def check_info_changed_code(code, change_type, kind, entry, comparison)
+        unless INFO_CHANGE_MODE_CODES.include?(code)
+          add_message('error',
+                      "The infoChanged extension on the #{kind} (sequence #{entry.sequence}) in the " \
+                      "#{comparison[:current_label]} has valueCode '#{code}', which is not in the PAS Information " \
+                      "Change Mode value set (allowed: #{INFO_CHANGE_MODE_CODES.join(', ')}).")
+          return
+        end
+
+        expected_code = change_type == 'added' ? 'added' : 'changed'
+        return if code == expected_code
+
+        descriptor = change_type == 'added' ? 'newly added' : 'modified or canceled'
+        add_message('error',
+                    "The infoChanged extension on the #{kind} (sequence #{entry.sequence}) in the " \
+                    "#{comparison[:current_label]} has valueCode '#{code}', but an entry that was #{descriptor} " \
+                    "relative to the #{comparison[:prior_label]} SHALL use valueCode '#{expected_code}' per the " \
+                    'value set definitions.')
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/workflows/pas_client_claim_update_entries_preserved_test.rb

@@ -0,0 +1,51 @@
+require_relative 'pas_client_claim_update_validation_utils'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    # spec-68
+    class PASClientClaimUpdateEntriesPreservedTest < Inferno::Test
+      include ClaimUpdateValidationUtils
+
+      id :pas_client_v221_claim_update_entries_preserved_test
+      title 'Claims updating a Claim preserve all prior item and supportingInfo entries'
+      description %(
+        The PAS IG [requires](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/conformancedetails.html#ci-c-spec-68)
+        that when changing the details of the request, the Claim contains all item and supportingInfo entries
+        from the original Claim and any previous update Claims, with `sequence` values preserved. This test
+        compares each detail-bearing Claim Update against the immediately prior Claim and confirms that every
+        prior item and supportingInfo sequence is still present.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-68',
+                            'hl7.fhir.us.davinci-pas_2.2.1@prof-5',
+                            'hl7.fhir.us.davinci-pas_2.2.1@prof-6'
+
+      run do
+        comparisons = claim_update_detail_comparisons
+        skip_if comparisons.empty?,
+                'Not enough consecutive Claim Update requests were received to verify entry preservation.'
+
+        comparisons.each do |comparison|
+          missing_items = entry_sequences(comparison[:prior].item) - entry_sequences(comparison[:current].item)
+          unless missing_items.empty?
+            add_message('error',
+                        "The #{comparison[:current_label]} Claim must retain all item entries from the " \
+                        "#{comparison[:prior_label]} Claim with their sequence values preserved. " \
+                        "Missing item sequence(s): #{missing_items.join(', ')}.")
+          end
+
+          missing_supporting_info =
+            entry_sequences(comparison[:prior].supportingInfo) - entry_sequences(comparison[:current].supportingInfo)
+          next if missing_supporting_info.empty?
+
+          add_message('error',
+                      "The #{comparison[:current_label]} Claim must retain all supportingInfo entries from the " \
+                      "#{comparison[:prior_label]} Claim with their sequence values preserved. " \
+                      "Missing supportingInfo sequence(s): #{missing_supporting_info.join(', ')}.")
+        end
+
+        assert_no_error_messages('One or more Claim Updates did not preserve all prior item or supportingInfo ' \
+                                 'entries. See Messages for details.')
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/workflows/pas_client_claim_update_grandparent_excluded_test.rb

@@ -0,0 +1,52 @@
+require_relative 'pas_client_claim_update_validation_utils'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    # spec-66
+    class PASClientClaimUpdateGrandparentExcludedTest < Inferno::Test
+      include ClaimUpdateValidationUtils
+
+      id :pas_client_v221_claim_update_grandparent_excluded_test
+      title 'Request Bundles updating an updated Claim omit the grandparent Claim'
+      description %(
+        The PAS IG [requires](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/conformancedetails.html#ci-c-spec-66)
+        that when the Claim being updated is itself a Claim Update, its referenced (grandparent) Claim is not
+        included. This test checks each Claim Update whose referenced Claim is itself an update and confirms
+        that the grandparent Claim is not included in the Bundle.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-66'
+
+      run do
+        applicable = received_claim_update_steps(claim_update_updates).filter_map do |step|
+          parent_reference = related_claim_references(step[:claim]).first
+          next if parent_reference.blank?
+
+          parent_entry = bundle_entry_for_reference(step[:bundle], parent_reference)
+          parent_claim = parent_entry&.resource
+          next unless parent_claim.is_a?(FHIR::Claim)
+
+          grandparent_reference = related_claim_references(parent_claim).first
+          next if grandparent_reference.blank? # the referenced Claim is not itself an update
+
+          step.merge(parent_reference:, grandparent_reference:)
+        end
+
+        skip_if applicable.empty?,
+                'No Claim Update referencing another Claim Update was received, so this requirement was not checked.'
+
+        applicable.each do |step|
+          grandparent_entry = bundle_entry_for_reference(step[:bundle], step[:grandparent_reference])
+          next if grandparent_entry.nil?
+
+          add_message('error',
+                      "In the #{step[:label]}, the included Claim (#{step[:parent_reference]}) is itself a Claim " \
+                      "Update, so its referenced Claim (#{step[:grandparent_reference]}) SHALL NOT be included in " \
+                      'the Bundle.')
+        end
+
+        assert_no_error_messages('One or more Claim Updates included the grandparent Claim that SHALL NOT be ' \
+                                 'present. See Messages for details.')
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/workflows/pas_client_claim_update_referenced_claim_test.rb

@@ -0,0 +1,46 @@
+require_relative 'pas_client_claim_update_validation_utils'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    # spec-65
+    class PASClientClaimUpdateReferencedClaimTest < Inferno::Test
+      include ClaimUpdateValidationUtils
+
+      id :pas_client_v221_claim_update_referenced_claim_test
+      title 'Request Bundles updating a Claim include the related Claim'
+      description %(
+        The PAS IG [requires](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/conformancedetails.html#ci-c-spec-65)
+        that the Claim being updated is referenced in the `Claim.related.claim` element and included in the
+        Bundle. This test checks each Claim Update made during this group and confirms that it references a
+        prior Claim and that the referenced Claim is present in the Bundle.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-65', 'hl7.fhir.us.davinci-pas_2.2.1@prof-4'
+
+      run do
+        steps = received_claim_update_steps(claim_update_updates)
+        skip_if steps.empty?, 'No Claim Update requests were received to verify.'
+
+        steps.each do |step|
+          references = related_claim_references(step[:claim])
+          if references.blank?
+            add_message('error',
+                        "The #{step[:label]} Claim must reference the Claim being updated in Claim.related.claim.")
+            next
+          end
+
+          references.each do |reference|
+            referenced_entry = bundle_entry_for_reference(step[:bundle], reference)
+            next if referenced_entry&.resource.is_a?(FHIR::Claim)
+
+            add_message('error',
+                        "The Claim referenced in Claim.related.claim (#{reference}) of the #{step[:label]} " \
+                        'must be included in the Bundle.')
+          end
+        end
+
+        assert_no_error_messages('One or more Claim Updates did not reference and include the Claim being ' \
+                                 'updated. See Messages for details.')
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/workflows/pas_client_claim_update_referenced_resources_test.rb

@@ -0,0 +1,43 @@
+require_relative 'pas_client_claim_update_validation_utils'
+require_relative '../../../cross_suite/pas_bundle_validation'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    # spec-67 - reuses the existing PasBundleValidation reference-presence logic.
+    class PASClientClaimUpdateReferencedResourcesTest < Inferno::Test
+      include ClaimUpdateValidationUtils
+      include DaVinciPASTestKit::PasBundleValidation
+
+      id :pas_client_v221_claim_update_referenced_resources_test
+      title 'Request Bundles updating a Claim include all resources referenced by the updated Claim'
+      description %(
+        The PAS IG [requires](https://hl7.org/fhir/us/davinci-pas/2.2.1/en/conformancedetails.html#ci-c-spec-67)
+        that all other referenced resources are included in the Bundle. This test checks each Claim Update made
+        during this group and confirms every resource referenced by the Claim is present in the Bundle exactly
+        once.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-67'
+
+      run do
+        steps = received_claim_update_steps
+        skip_if steps.empty?, 'No Claim Update requests were received to verify.'
+
+        steps.each do |step|
+          bundle = step[:bundle]
+          base_url = extract_base_url(bundle.entry.first&.fullUrl)
+          # The reused reference-presence check verifies the primary Update Claim's parent reference and the
+          # parent's own referenced resources, while skipping a non-primary Claim's `related` so the
+          # deliberately-omitted grandparent (spec-65/66) is not flagged as missing.
+          validation_error_messages.clear
+          check_presence_of_referenced_resources(step[:claim], base_url, bundle.entry)
+          validation_error_messages.each do |message|
+            add_message('error', "In the #{step[:label]} request: #{message}")
+          end
+        end
+
+        assert_no_error_messages('Not all resources referenced by a Claim Update are included in the Bundle ' \
+                                 'exactly once. See Messages for details.')
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/workflows/pas_client_claim_update_submit_tests.rb

@@ -0,0 +1,238 @@
+require_relative '../urls'
+require_relative '../../client_input_descriptions'
+require_relative '../../user_input_response'
+require_relative '../../session_identification'
+require_relative '../../../cross_suite/tags'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    # Shared behavior for the Claim Update "wait" tests. Each subclass waits for a
+    # single `$submit` request from the client and, on receipt, returns the response
+    # configured through its dedicated response input (or an Inferno-generated approval
+    # if none was provided). Subclasses differ only in:
+    #   - their dedicated response input + `submit_respond_with`
+    #   - the unique `claim_update_tag` used to tag the received request
+    #   - the instructions shown to the tester (`interaction_instructions`)
+    #
+    # These tests auto-continue when a request is received (they do not set
+    # `accepts_multiple_requests`, so `ClaimEndpoint#update_result` marks the result
+    # `pass` and resumes the wait), and they never trigger a Subscription notification
+    # (`suppress_notifications` is honored by `ClaimEndpoint#make_response`), even when
+    # the configured response indicates the request was pended.
+    class AbstractClaimUpdateSubmitTest < Inferno::Test
+      include URLs
+      include SessionIdentification
+      include UserInputResponse
+
+      id :pas_client_v221_claim_update_submit_base
+
+      config options: { suppress_notifications: true }
+
+      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
+
+      run do
+        response_input = config.options[:submit_respond_with]
+        if response_input.present? && send(response_input).present?
+          assert_valid_json send(response_input),
+                            "Input '#{input_title(response_input)}' must be valid JSON"
+        elsif response_input.present?
+          add_message('info', %(
+            No response provided in input '#{input_title(response_input)}'. Inferno will generate an
+            approved response to the $submit request from the submitted Claim.
+          ))
+        end
+
+        wait_identifier = session_wait_identifier(client_id, session_url_path)
+        submit_endpoint = session_endpoint_url(:submit, client_id, session_url_path)
+
+        wait(
+          identifier: wait_identifier,
+          timeout: 600,
+          message: claim_update_wait_message(submit_endpoint)
+        )
+      end
+
+      def claim_update_wait_message(submit_endpoint)
+        %(
+          **Claim Update Workflow**
+
+          #{interaction_instructions}
+
+          Submit the request to
+
+          `#{submit_endpoint}`
+
+          #{response_note}
+
+          Inferno will automatically continue once it receives the request, so no further
+          action is required after submitting.
+        )
+      end
+
+      def response_note
+        response_input = config.options[:submit_respond_with]
+        if response_input.present? && send(response_input).present?
+          "The response provided in the '**#{input_title(response_input)}**' input will be returned, " \
+            'updated with current timestamps.'
+        else
+          'Inferno will generate an approved response from the submitted Claim and return it.'
+        end
+      end
+
+      # Overridden by subclasses to describe the specific submission the tester should make.
+      def interaction_instructions
+        raise NotImplementedError, "#{self.class} must implement #interaction_instructions"
+      end
+    end
+
+    # Step 1: the initial prior authorization submission that subsequent updates build on.
+    class PASClientClaimUpdateInitialSubmitTest < AbstractClaimUpdateSubmitTest
+      id :pas_client_v221_claim_update_initial_submit_test
+      title 'PAS client submits an initial prior authorization request'
+      description %(
+        Inferno waits for an initial prior authorization `$submit` request from the client.
+        This establishes the original Claim that the subsequent updates will reference and
+        modify. Upon receipt, Inferno returns the configured response (or generates an
+        approved response from the submitted Claim) and continues automatically.
+      )
+
+      input :claim_update_initial_response,
+            title: 'Initial claim response JSON',
+            type: 'textarea',
+            optional: true,
+            description: %(
+              If provided, this JSON will be returned in response to the initial `$submit` request,
+              updated with current timestamps. If not provided, an approved response will be generated
+              from the submitted Claim.
+            )
+
+      submit_respond_with :claim_update_initial_response
+      config options: { claim_update_tag: CLAIM_UPDATE_INITIAL_TAG }
+
+      def interaction_instructions
+        'Submit an **initial** prior authorization request (a `$submit` containing a Claim with one ' \
+          'or more items and no `Claim.related.claim`).'
+      end
+    end
+
+    # Step 2: an update that adds a new item to the previously submitted Claim.
+    class PASClientClaimUpdateAddItemSubmitTest < AbstractClaimUpdateSubmitTest
+      id :pas_client_v221_claim_update_add_item_submit_test
+      title 'PAS client submits an update that adds an item'
+      description %(
+        Inferno waits for an updated prior authorization `$submit` request that adds a new item to
+        the previously submitted Claim. The update is expected to reference the original Claim in
+        `Claim.related.claim` (and include it in the Bundle), retain all previously submitted item
+        and supportingInfo entries with their `sequence` values, and mark the newly added item with
+        an `infoChanged` extension. Upon receipt, Inferno returns the configured response and
+        continues automatically.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-63'
+
+      input :claim_update_add_item_response,
+            title: 'Add-item update response JSON',
+            type: 'textarea',
+            optional: true,
+            description: %(
+              If provided, this JSON will be returned in response to the add-item update `$submit`
+              request, updated with current timestamps. If not provided, an approved response will be
+              generated from the submitted Claim.
+            )
+
+      submit_respond_with :claim_update_add_item_response
+      config options: { claim_update_tag: CLAIM_UPDATE_ADD_ITEM_TAG }
+
+      def interaction_instructions
+        'Submit an **update that adds a new item** to the prior authorization. Reference the ' \
+          'previously submitted Claim in `Claim.related.claim` and include that Claim in the Bundle, ' \
+          'retain all previously submitted items and supportingInfo (preserving their `sequence` ' \
+          'values), and mark the newly added item with an `infoChanged` extension.'
+      end
+    end
+
+    # Step 3: an update that modifies one item and cancels another.
+    class PASClientClaimUpdateModifyCancelSubmitTest < AbstractClaimUpdateSubmitTest
+      id :pas_client_v221_claim_update_modify_cancel_submit_test
+      title 'PAS client submits an update that modifies an item and cancels an item'
+      description %(
+        Inferno waits for a second updated prior authorization `$submit` request that modifies one
+        existing item and cancels another. Modified entries are expected to carry an `infoChanged`
+        extension; the canceled item is expected to carry the `infoCancelled` modifier extension
+        (valueBoolean `true`), a `certificationType` extension with code `3` (Cancel) in
+        `Claim.item.extension`, and an `infoChanged` extension. All prior item and supportingInfo
+        entries are expected to be retained with preserved `sequence` values, referencing the
+        immediately prior Claim update. Upon receipt, Inferno returns the configured response and
+        continues automatically.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-63'
+
+      input :claim_update_modify_cancel_response,
+            title: 'Modify-and-cancel update response JSON',
+            type: 'textarea',
+            optional: true,
+            description: %(
+              If provided, this JSON will be returned in response to the modify-and-cancel update
+              `$submit` request, updated with current timestamps. If not provided, an approved response
+              will be generated from the submitted Claim.
+            )
+
+      submit_respond_with :claim_update_modify_cancel_response
+      config options: { claim_update_tag: CLAIM_UPDATE_MODIFY_CANCEL_TAG }
+
+      def interaction_instructions
+        'Submit an **update that modifies one item and cancels another**. Mark the modified item ' \
+          'with an `infoChanged` extension. Mark the canceled item with the `infoCancelled` modifier ' \
+          'extension (valueBoolean `true`), a `certificationType` extension with code `3` (Cancel) in ' \
+          '`Claim.item.extension`, and an `infoChanged` extension. Retain all prior items and ' \
+          'supportingInfo (preserving their `sequence` values) and reference the immediately prior ' \
+          'Claim update in `Claim.related.claim`.'
+      end
+    end
+
+    # Step 4: an update that cancels the entire prior authorization request.
+    class PASClientClaimUpdateCancelAllSubmitTest < AbstractClaimUpdateSubmitTest
+      id :pas_client_v221_claim_update_cancel_all_submit_test
+      title 'PAS client submits an update that cancels the entire request'
+      description %(
+        Inferno waits for a third updated prior authorization `$submit` request that cancels the
+        entire prior authorization. The update is expected to include a `certificationType` extension
+        with code `3` (Cancel) in `Claim.extension`; no items are required to cancel the entire
+        authorization. The update is expected to reference the immediately prior Claim update in
+        `Claim.related.claim`. Upon receipt, Inferno returns the configured response and continues
+        automatically.
+      )
+      verifies_requirements 'hl7.fhir.us.davinci-pas_2.2.1@spec-63'
+
+      input :claim_update_cancel_all_response,
+            title: 'Cancel-entire-request update response JSON',
+            type: 'textarea',
+            optional: true,
+            description: %(
+              If provided, this JSON will be returned in response to the cancel-entire-request update
+              `$submit` request, updated with current timestamps. If not provided, an approved response
+              will be generated from the submitted Claim.
+            )
+
+      submit_respond_with :claim_update_cancel_all_response
+      config options: { claim_update_tag: CLAIM_UPDATE_CANCEL_ALL_TAG }
+
+      def interaction_instructions
+        'Submit an **update that cancels the entire prior authorization**. Include a ' \
+          '`certificationType` extension with code `3` (Cancel) in `Claim.extension`; no items are ' \
+          'required to cancel the entire authorization. Reference the immediately prior Claim update ' \
+          'in `Claim.related.claim`.'
+      end
+    end
+  end
+end