davinci_pas_test_kit 0.15.1 → 0.16.0

data/lib/davinci_pas_test_kit/client/abstract_approval_submit_test.rb

@@ -11,22 +11,19 @@ module DaVinciPASTestKit
     id :pas_client_approval_submit_test
     title 'PAS client submits a claim using the $submit operation'
     description %(
-      Inferno will wait for a prior authorization submission request
-      from the client. Upon receipt, Inferno will generate and send a
-      response with an approved status.
+      During this test, Inferno will wait for a prior authorization submission request
+      from the PAS client using the `$submit` operation. Upon receipt, Inferno will respond
+      with a [tester-provided](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#tester-directed-custom-responses)
+      or [Inferno-mocked](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#mocked-responses)
+      approval response. Inferno will not respond to `$inquire` operation requests during
+      this test.
     )
 
     input :approval_json_response,
           title: 'Claim approved response JSON',
           type: 'textarea',
           optional: true,
-          description: %(
-            If provided, this JSON will be sent in response to $submit requests during this test
-            to indicate that the request has been approved.
-            It will be updated to make creation timestamps current.
-            If not provided, an approval response will be generated from the submitted Claim.
-            In either case, the response will be validated against the PAS Response Bundle profile.
-          )
+          description: DaVinciPASTestKit.user_response_input_description('$submit', 'approved', 'Approval Response')
     input :client_id,
           title: 'Client Id',
           type: 'text',
@@ -41,9 +38,10 @@ module DaVinciPASTestKit
           description: INPUT_SESSION_URL_PATH_LOCKED
 
     submit_respond_with :approval_json_response
+    config options: { submit_enabled: true }
 
     run do
-      if user_inputted_response? :approval_json_response
+      if user_inputted_response?(:approval_json_response)
         assert_valid_json approval_json_response,
                           'Input "Claim approved response JSON" must be valid JSON'
       else
@@ -58,17 +56,30 @@ module DaVinciPASTestKit
 
       wait(
         identifier: wait_identifier,
-        message: %(
-          **Approval Workflow Test**:
+        message: <<~MESSAGE
+          **Approval Scenario Test**:
+
+          Inferno will wait while the tester uses the PAS client to submit a PAS request to
+          Inferno. The tests will automatically continue once a request has been received.
+
+          ### Endpoints
 
           Submit a PAS request to
 
           `#{submit_endpoint}`
 
-          If the optional '**#{input_title(:approval_json_response)}**' input is populated, it will
-          be returned, updated with current timestamps. Otherwise, an approval response will
-          be generated by Inferno using the received Claim.
-        )
+          ### Authentication and Identification
+
+          #{auth_description_for_wait(client_id)}
+
+          ### Responses
+
+          #{response_description_for_wait(user_inputted_response?(:approval_json_response),
+                                          input_title(:approval_json_response),
+                                          '$submit')}
+
+          Inferno will not respond to `$inquire` requests during this test.
+        MESSAGE
       )
     end
   end

data/lib/davinci_pas_test_kit/client/abstract_denial_submit_test.rb

@@ -11,22 +11,19 @@ module DaVinciPASTestKit
     id :pas_client_denial_submit_test
     title 'PAS client submits a claim using the $submit operation'
     description %(
-      Inferno will wait for a prior authorization submission request
-      from the client. Upon receipt, Inferno will respond with the
-      provided denial response.
+      During this test, Inferno will wait for a prior authorization submission request
+      from the PAS client using the `$submit` operation. Upon receipt, Inferno will respond
+      with a [tester-provided](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#tester-directed-custom-responses)
+      or [Inferno-mocked](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#mocked-responses)
+      denial response. Inferno will not respond to `$inquire` operation requests during
+      this test.
     )
 
     input :denial_json_response,
           title: 'Claim denied response JSON',
           type: 'textarea',
           optional: true,
-          description: %(
-            If provided, this JSON will be sent in response to $submit requests during this test
-            to indicate that the request has been denied.
-            It will be updated to make creation timestamps current.
-            If not provided, a denial response will be generated from the submitted Claim.
-            In either case, the response will be validated against the PAS Response Bundle profile.
-          )
+          description: DaVinciPASTestKit.user_response_input_description('$submit', 'denied', 'Denial Response')
     input :client_id,
           title: 'Client Id',
           type: 'text',
@@ -40,6 +37,7 @@ module DaVinciPASTestKit
           locked: true,
           description: INPUT_SESSION_URL_PATH_LOCKED
     submit_respond_with :denial_json_response
+    config options: { submit_enabled: true }
 
     run do
       if user_inputted_response? :denial_json_response
@@ -57,17 +55,29 @@ module DaVinciPASTestKit
 
       wait(
         identifier: wait_identifier,
-        message: %(
-          **Denial Workflow Test**:
+        message: <<~MESSAGE
+          **Denial Scenario Test**:
+
+          Inferno will wait while the tester uses the PAS client to submit a PAS request to
+          Inferno. The tests will automatically continue once a request has been received.
+
+          ### Endpoints
 
           Submit a PAS request to
 
           `#{submit_endpoint}`
 
-          If the optional '**#{input_title(:denial_json_response)}**' input is populated, it will
-          be returned, updated with current timestamps. Otherwise, a denial response will
-          be generated by Inferno using the received Claim.
-        )
+          ### Authentication and Identification
+
+          #{auth_description_for_wait(client_id)}
+
+          ### Responses
+
+          #{response_description_for_wait(user_inputted_response?(:denial_json_response),
+                                          input_title(:denial_json_response),
+                                          '$submit')}
+          Inferno will not respond to `$inquire` requests during this test.
+        MESSAGE
       )
     end
   end

data/lib/davinci_pas_test_kit/client/abstract_gather_must_support_test.rb

@@ -1,30 +1,30 @@
 require_relative 'client_input_descriptions'
 require_relative 'session_identification'
+require_relative 'user_input_response'
 
 module DaVinciPASTestKit
   # abstract test, needs to be extended to include a version-specific URLs module
   class AbstractGatherMustSupportTest < Inferno::Test
     include SessionIdentification
+    include UserInputResponse
 
     id :pas_client_gather_must_support
     title 'PAS client submits Claims using the $submit and $inquire operations to demonstrate coverage of must ' \
           'support elements'
     description %(
-      This test allows the client to send both $submit and $inquire requests for Inferno to evaluate
-      coverage of must support elements in both requests and responses. Any requests made during
-      previous workflow tests will also be considered.
+      During this test, Inferno will wait while the tester uses the PAS client to make `$submit`
+      and `$inquire` operation requests against Inferno demonstrating any request and response
+      must support elements not yet demonstrated.
 
       Because Inferno's mocked responses do not cover all must support elements, in order to pass
       these tests testers will need to provide response bundles for Inferno to return when
-      responding to $submit and $inquire requests. Each response input takes a single entry or a
-      JSON list of entries, where each entry is either a FHIR Bundle or a wrapper object pairing
-      a Bundle with selection criteria. For each request, Inferno will respond with the Bundle of
-      the first entry whose criteria are all met, generating a default response if none match.
-      See the input descriptions for details on the wrapper format, the supported criteria, and
-      on substituting values from the request into the returned response.
-
-      This enables testers to verify that their client can handle responses containing all required
-      must support elements.
+      responding to `$submit` and `$inquire` requests. Each response input takes a JSON list of entries,
+      where each entry specifies a Bundle with selection criteria ([format](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#response-option-format)).
+      For each request received during this test, 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.
     )
 
     input :client_id,
@@ -43,59 +43,13 @@ module DaVinciPASTestKit
           title: 'Must Support $submit Response Bundles',
           type: 'textarea',
           optional: true,
-          description: %(
-            An optional JSON value specifying response Bundles for Inferno to return when
-            responding to $submit requests during must support testing. Provide a single entry
-            or a list of entries, where each entry is either a FHIR Bundle or a wrapper object
-            of the form `{"criteria": {...}, "bundle": {...}}` pairing a FHIR Bundle with the
-            selection criteria that a request must meet for that Bundle to be returned.
-
-            For each request, Inferno will respond with the Bundle of the first entry whose
-            criteria are all met. An entry with no criteria (including a bare Bundle) matches
-            any request, and an entry with multiple criteria must meet all of them. If no entry
-            matches, or none are provided, Inferno will generate a default response. Supported
-            `criteria` keys:
-
-            - `requestRange`: a string of comma-separated request numbers or ranges, e.g.,
-              `"1-2,4"`. Met when the number of $submit requests received during this test,
-              counting this one, is among the listed values.
-            - `fhirpath`: a FHIRPath expression evaluated against the incoming request Bundle.
-              Met when the expression evaluates to a single truthy value.
-
-            A Bundle may also contain tokens of the form `{{fhirpath}}`, e.g.,
-            `{{Bundle.entry.first().resource.id}}`. Inferno replaces each token in the returned
-            Bundle with the result of evaluating the FHIRPath expression against the incoming
-            request Bundle.
-          )
+          description: DaVinciPASTestKit.ms_responses_input_description('$submit')
     input :ms_inquire_responses,
           title: 'Must Support $inquire Response Bundles',
           type: 'textarea',
           optional: true,
-          description: %(
-            An optional JSON value specifying response Bundles for Inferno to return when
-            responding to $inquire requests during must support testing. Provide a single entry
-            or a list of entries, where each entry is either a FHIR Bundle or a wrapper object
-            of the form `{"criteria": {...}, "bundle": {...}}` pairing a FHIR Bundle with the
-            selection criteria that a request must meet for that Bundle to be returned.
-
-            For each request, Inferno will respond with the Bundle of the first entry whose
-            criteria are all met. An entry with no criteria (including a bare Bundle) matches
-            any request, and an entry with multiple criteria must meet all of them. If no entry
-            matches, or none are provided, Inferno will generate a default response. Supported
-            `criteria` keys:
-
-            - `requestRange`: a string of comma-separated request numbers or ranges, e.g.,
-              `"1-2,4"`. Met when the number of $inquire requests received during this test,
-              counting this one, is among the listed values.
-            - `fhirpath`: a FHIRPath expression evaluated against the incoming request Bundle.
-              Met when the expression evaluates to a single truthy value.
-
-            A Bundle may also contain tokens of the form `{{fhirpath}}`, e.g.,
-            `{{Bundle.entry.first().resource.id}}`. Inferno replaces each token in the returned
-            Bundle with the result of evaluating the FHIRPath expression against the incoming
-            request Bundle.
-          )
-    config options: { accepts_multiple_requests: true }
+          description: DaVinciPASTestKit.ms_responses_input_description('$inquire')
+    config options: { accepts_multiple_requests: true, submit_enabled: true, inquire_enabled: true }
     output :confirmation_url
 
     run do
@@ -107,11 +61,17 @@ module DaVinciPASTestKit
 
       wait(
         identifier: wait_identifier,
-        message: %(
-          The client system may now make multiple $submit and $inquire requests before continuing.
-          These requests should cumulatively demonstrate coverage of all required profiles and all
-          must support elements within those profiles, as specified by the DaVinci Prior Authorization
-          Support implementation guide.
+        message: <<~MESSAGE
+          **Additional Must Support Demonstration**:
+
+          Inferno will wait while the tester uses the PAS client to make additional $submit and $inquire requests.
+          Along with the requests submitted during previous tests, these requests and their responses must
+          cumulatively demonstrate coverage of all required profiles and all must support elements within
+          those profiles, as specified by the PAS IG.
+
+          [Click here](#{confirmation_url}) when all requests have been submitted.
+
+          ### Required Profiles
 
           For the $submit operation the required profiles include:
           - PAS Request Bundle
@@ -141,19 +101,30 @@ module DaVinciPASTestKit
           - PAS Practitioner
           - PAS PractitionerRole
 
-          If you would like Inferno to respond with specific response bundles (to demonstrate
-          must support coverage on responses), provide them in the input fields above.
+          ### Endpoints
+
+          Submit PAS requests to
+
+          - $submit: `#{submit_endpoint}`
+          - $inquire: `#{inquire_endpoint}`
+
+          ### Authentication and Identification
+
+          #{auth_description_for_wait(client_id)}
 
-          Submit PAS $submit requests to
+          ### Submit Responses
 
-          `#{submit_endpoint}`
+          #{response_description_for_wait(user_inputted_response?(:ms_submit_responses),
+                                          input_title(:ms_submit_responses),
+                                          '$submit')}
 
-          Submit PAS $inquire requests to
+          ### Inquire Responses
 
-          `#{inquire_endpoint}`
+          #{response_description_for_wait(user_inputted_response?(:ms_inquire_responses),
+                                          input_title(:ms_inquire_responses),
+                                          '$inquire')}
 
-          and [click here](#{confirmation_url}) when done.
-        )
+        MESSAGE
       )
     end
   end

data/lib/davinci_pas_test_kit/client/abstract_modification_submit_test.rb

@@ -11,25 +11,21 @@ module DaVinciPASTestKit
     id :pas_client_modification_submit_test
     title 'PAS client submits a claim using the $submit operation'
     description %(
-      Inferno will wait for a prior authorization submission request
-      from the client. Upon receipt, Inferno will generate and send a
-      response in which the payer authorizes items that differ from those
-      that were requested (a "payer modification").
+      During this test, Inferno will wait for a prior authorization submission request
+      from the PAS client using the `$submit` operation. Upon receipt, Inferno will respond
+      with a [tester-provided](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#tester-directed-custom-responses)
+      or [Inferno-mocked](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Controlling-Simulated-Responses#mocked-responses)
+      a response in which the payer authorizes items that differ from those that were
+      requested (a "payer modification"). Inferno will not respond to `$inquire`
+      operation requests during this test.
     )
 
     input :modification_json_response,
           title: 'Claim modified response JSON',
           type: 'textarea',
           optional: true,
-          description: %(
-            If provided, this JSON will be sent in response to $submit requests during this test
-            to indicate that the payer authorized items that differ from those requested.
-            It will be updated to make creation timestamps current.
-            If not provided, a payer modification response will be generated from the submitted Claim,
-            marking each item as modified (adjudication status A6) and adding a corresponding
-            `ClaimResponse.addItem` describing what was actually authorized.
-            In either case, the response will be validated against the PAS Response Bundle profile.
-          )
+          description: DaVinciPASTestKit.user_response_input_description('$submit', 'modified by the payer',
+                                                                         'Payer Modifications')
     input :client_id,
           title: 'Client Id',
           type: 'text',
@@ -44,6 +40,7 @@ module DaVinciPASTestKit
           description: INPUT_SESSION_URL_PATH_LOCKED
 
     submit_respond_with :modification_json_response
+    config options: { submit_enabled: true }
 
     run do
       if user_inputted_response? :modification_json_response
@@ -61,17 +58,30 @@ module DaVinciPASTestKit
 
       wait(
         identifier: wait_identifier,
-        message: %(
-          **Payer Modification Workflow Test**:
+        message: <<~MESSAGE
+          **Payer Modification Scenario Test**:
+
+          Inferno will wait while the tester uses the PAS client to submit a PAS request to
+          Inferno. The tests will automatically continue once a request has been received.
+
+          ### Endpoints
 
           Submit a PAS request to
 
           `#{submit_endpoint}`
 
-          If the optional '**#{input_title(:modification_json_response)}**' input is populated, it will
-          be returned, updated with current timestamps. Otherwise, a payer modification response will
-          be generated by Inferno using the received Claim.
-        )
+          ### Authentication and Identification
+
+          #{auth_description_for_wait(client_id)}
+
+          ### Responses
+
+          #{response_description_for_wait(user_inputted_response?(:modification_json_response),
+                                          input_title(:modification_json_response),
+                                          '$submit')}
+
+          Inferno will not respond to `$inquire` requests during this test.
+        MESSAGE
       )
     end
   end

data/lib/davinci_pas_test_kit/client/abstract_response_attest.rb

@@ -1,12 +1,16 @@
+require_relative 'request_count_gating'
+
 module DaVinciPASTestKit
   # abstract test, needs to be extended to include a version-specific URLs module
   class AbstractResponseAttest < Inferno::Test
+    include RequestCountGating
+
     id :pas_client_response_attest
     title 'PAS client reacts appropriately to the response'
     description %(
-      This test provides the tester an opportunity to observe their client following
-      the receipt of response and attest that users are able to see the appropriate
-      updates to the corresponding prior authorization request in their system.
+      During this test, the tester will observe the PAS client following
+      the receipt of a response and attest that users are able to see the appropriate
+      updates to the corresponding prior authorization request.
     )
     attestation
 
@@ -14,12 +18,23 @@ module DaVinciPASTestKit
       config.options[:workflow_tag]
     end
 
+    def operation_tag
+      config.options[:operation_tag]
+    end
+
     def attest_message
       config.options[:attest_message]
     end
 
+    # workflow_tag may be a single tag or an Array of tags (e.g. the Claim Update attest tests,
+    # which match requests across several update steps); normalized to an Array so callers don't
+    # each need their own is_a?(Array) check.
+    def workflow_tags
+      Array(workflow_tag)
+    end
+
     def workflow_name
-      case workflow_tag
+      case workflow_tags.first
       when APPROVAL_WORKFLOW_TAG
         'Approval'
       when DENIAL_WORKFLOW_TAG
@@ -34,6 +49,33 @@ module DaVinciPASTestKit
         'Operation Failure'
       when PROCESSING_ERROR_WORKFLOW_TAG
         'Processing Error'
+      when CLAIM_UPDATE_INITIAL_TAG
+        'Claim Update'
+      else
+        raise Inferno::Exceptions::TestSuiteImplementationException.new('PAS Display Attestation',
+                                                                        "No name for workflow tag #{workflow_tag}.")
+      end
+    end
+
+    # Tags identifying the requests that gate the attestation, when they aren't the ones tagged with
+    # workflow_tag (+ operation_tag) - e.g., the notification Inferno sends to the client.
+    def request_tags
+      config.options[:request_tags]
+    end
+
+    def target_requests
+      return load_tagged_requests(*request_tags) if request_tags.present?
+
+      workflow_tags.flat_map do |one_workflow_tag|
+        load_tagged_requests(*[one_workflow_tag, operation_tag].compact)
+      end
+    end
+
+    def unexpected_error_status_message(error_responses)
+      if error_responses.any? { |r| r.direction == 'outgoing' }
+        'Skipping attestation: the PAS client did not return a successful response to Inferno\'s request.'
+      else
+        'Skipping attestation: Inferno expected to return a successful response, but did not.'
       end
     end
 
@@ -41,7 +83,34 @@ module DaVinciPASTestKit
     output :attest_false_url
 
     run do
-      identifier = test_session_id
+      # check that there are actually requests
+      # - skip if none unless there is a config
+      # - raise an implementation error if there are more than 1 unless config set (shouldn't ever)
+      # - skip if no response has the expected HTTP status (success, or error when error_status_expected)
+
+      requests = target_requests
+      if requests.empty?
+        if no_requests_ok?
+          pass 'Attestation not needed: no requests received or required for this group.'
+        else
+          skip "Skipping attestation: No requests made demonstrating the #{workflow_name} scenario."
+        end
+      elsif requests.length > 1 && !multiple_requests_ok?
+        raise Inferno::Exceptions::TestSuiteImplementationException.new(
+          'PAS request tagging',
+          "multiple requests tagged with workflow tag #{workflow_tag}."
+        )
+      else
+        success_responses, error_responses = requests.partition { |r| r.status.to_s.start_with?('2') }
+        if error_responses.blank? && config.options[:error_status_expected]
+          skip 'Skipping attestation: Inferno expected to return a HTTP error response, but did not.'
+        elsif success_responses.blank? && !config.options[:error_status_expected]
+          skip unexpected_error_status_message(error_responses)
+        end
+      end
+
+      # only the tester continues this wait, so use a fresh random identifier - see SessionIdentification
+      identifier = SecureRandom.uuid
       attest_true_url = "#{resume_pass_url}?token=#{identifier}"
       output(attest_true_url:)
       attest_false_url = "#{resume_fail_url}?token=#{identifier}"
@@ -50,7 +119,7 @@ module DaVinciPASTestKit
       wait(
         identifier:,
         message: %(
-          **#{workflow_name} Workflow Test**:
+          **#{workflow_name} Scenario Test**:
 
           #{attest_message}
 

data/lib/davinci_pas_test_kit/client/abstract_subscription_create_test.rb

@@ -9,7 +9,7 @@ module DaVinciPASTestKit
     id :pas_client_subscription_create_test
     title 'PAS client submits a Subscription creation request'
     description %(
-      Inferno will wait for a Subscription creation request
+      During this test, Inferno will wait for a Subscription creation request
       and then perform a handshake to activate the Subscription.
     )
 
@@ -29,9 +29,9 @@ module DaVinciPASTestKit
           optional: true,
           title: 'Client Notification Access Token',
           description: %(
-            The bearer token that Inferno will send on requests to the client under test's rest-hook notification
-            endpoint, including handshake notifications sent after Subscription creation. Not needed if the client
-            under test will create a Subscription with an appropriate header value in the `channel.header` element.
+            The bearer token that Inferno will send on requests to the PAS client's rest-hook notification
+            endpoint, including handshake notifications sent after Subscription creation. Not needed if the PAS client
+            will create a Subscription with an appropriate header value in the `channel.header` element.
             If a value for the `authorization` header is provided in `channel.header`, this value will override it.
           )
 
@@ -41,16 +41,33 @@ module DaVinciPASTestKit
 
       wait(
         identifier: wait_identifier,
-        message: %(
+        message: <<~MESSAGE
           **Subscription Creation Test**:
 
-          Submit a POST with a Subscription to:
+          Inferno will wait while the tester uses the PAS client to create a Subscription on
+          Inferno's simulated payer server. Inferno [will not accept all Subscriptions](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Subscriptions-and-Notifications#subscription-validation)
+          but a Subscription does not need to be fully conformant to be accepted.
+
+          After accepting a Subscription, Inferno will send a handshake notification
+          to the specified `channel.endpoint` and continue automatically.
+
+          ### Endpoints
+
+          Submit a POST with a Subscription to
 
           `#{subscription_endpoint}`
 
-          Upon receipt, Inferno will send a handshake request to verify that notifications can be
-          delivered and continue the test with a pass or fail based on the result.
-        )
+          ### Authentication and Identification
+
+          #{auth_description_for_wait(client_id)}
+
+          ### Responses and Handshake Notifications
+
+          The PAS Test Kit wiki contains details on the supported responses and
+          notifications that the PAS client can expect to receive during these tests:
+          - [Subscription creation responses](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Subscriptions-and-Notifications#creation-response)
+          - [Handshake notification](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Subscriptions-and-Notifications#handshake-notification)
+        MESSAGE
       )
     end
   end