davinci_pas_test_kit 0.14.0 → 0.15.0

data/lib/davinci_pas_test_kit/client/v2.2.1/client_suite.rb

@@ -0,0 +1,240 @@
+require 'subscriptions_test_kit'
+require 'udap_security_test_kit'
+require 'smart_app_launch_test_kit'
+require_relative '../../cross_suite/validator_suppressions'
+require_relative '../../cross_suite/tags'
+require_relative '../endpoints/claim_endpoint'
+require_relative '../endpoints/token_endpoint'
+require_relative '../endpoints/subscription_create_endpoint'
+require_relative '../endpoints/subscription_status_endpoint'
+require_relative '../metadata/mock_pas_server'
+require_relative '../pas_client_options'
+require_relative 'pas_client_workflows_group'
+require_relative 'pas_client_must_support_group'
+require_relative 'pas_client_subscription_setup_group'
+require_relative 'pas_client_registration_group'
+require_relative 'pas_client_auth_smart_group'
+require_relative 'pas_client_auth_udap_group'
+require_relative 'pas_client_error_handling_group'
+require_relative '../client_input_descriptions'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    class ClientSuite < Inferno::TestSuite
+      id :davinci_pas_client_suite_v221
+      title 'Da Vinci PAS Client Suite v2.2.1'
+      description <<~DESCRIPTION
+        The Da Vinci PAS Client v2.2.1 Test Suite tests the conformance of systems to the
+        capabilities of a PAS client as described in [version 2.2.1](https://hl7.org/fhir/us/davinci-pas/2.2.1)
+        of the Da Vinci Prior Authorization Support (PAS) Implementation Guide.
+
+        These tests are a **DRAFT** intended to allow PAS implementers to perform
+        preliminary checks of their implementations against the PAS IG requirements and
+        [provide feedback](https://github.com/inferno-framework/davinci-pas-test-kit/issues) on the tests.
+        Future versions of these tests may validate other requirements and may change how these are tested.
+
+        Detailed information about this test suite can be found in the
+        [client section](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Details) of the
+        [PAS Test Kit Wiki](https://github.com/inferno-framework/davinci-pas-test-kit/wiki), including:
+        - [What testers need to successfully execute these tests](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Instructions-v2.2.1#pre-execution-setup-and-required-information),
+        - [Minimal](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Instructions-v2.2.1#quick-start)
+          and [complete](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Instructions-v2.2.1#additional-testing-options)
+          instructions for executing against a client system, and
+        - How to [interpret test results](https://github.com/inferno-framework/davinci-pas-test-kit/wiki/Client-Instructions-v2.2.1#interpreting-results).
+      DESCRIPTION
+
+      suite_summary <<~SUMMARY
+        The Da Vinci PAS Client v2.2.1 Test Suite tests the conformance of client systems
+        to [version 2.2.1 of the Da Vinci Prior Authorization Support (PAS)
+        Implementation Guide](https://hl7.org/fhir/us/davinci-pas/2.2.1).
+      SUMMARY
+
+      links [
+        {
+          label: 'Report Issue',
+          url: 'https://github.com/inferno-framework/davinci-pas-test-kit/issues/'
+        },
+        {
+          label: 'Open Source',
+          url: 'https://github.com/inferno-framework/davinci-pas-test-kit/'
+        },
+        {
+          label: 'Download',
+          url: 'https://github.com/inferno-framework/davinci-pas-test-kit/releases'
+        },
+        {
+          label: 'Implementation Guide',
+          url: 'https://hl7.org/fhir/us/davinci-pas/2.2.1/'
+        }
+      ]
+
+      requirement_sets(
+        {
+          identifier: 'hl7.fhir.us.davinci-pas_2.2.1',
+          title: 'Da Vinci Prior Authorization Support (PAS) v2.2.1',
+          actor: 'PAS Client'
+        },
+        {
+          identifier: 'hl7.fhir.uv.subscriptions_1.1.0',
+          title: 'Subscriptions R5 Backport IG',
+          actor: 'Client'
+        }
+      )
+
+      fhir_resource_validator do
+        igs('hl7.fhir.us.davinci-pas#2.2.1', 'hl7.fhir.us.core#6.1.0')
+
+        exclude_message do |message|
+          # Messages expected of the form `<ResourceType>: <FHIRPath>: <message>`
+          # We strip `<ResourceType>: <FHIRPath>: ` for the sake of matching
+          SUPPRESSED_MESSAGES.match?(message.message.sub(/\A\S+: \S+: /, ''))
+        end
+      end
+
+      suite_option :client_type,
+                   title: 'Client Security Type',
+                   list_options: [
+                     {
+                       label: 'SMART Backend Services',
+                       value: PASClientOptions::SMART_BACKEND_SERVICES_CONFIDENTIAL_ASYMMETRIC
+                     },
+                     {
+                       label: 'UDAP B2B Client Credentials',
+                       value: PASClientOptions::UDAP_CLIENT_CREDENTIALS
+                     },
+                     {
+                       label: 'Other Authentication',
+                       value: PASClientOptions::OTHER_AUTH
+                     }
+                   ]
+
+      route(:get, UDAPSecurityTestKit::UDAP_DISCOVERY_PATH, lambda { |_env|
+        UDAPSecurityTestKit::MockUDAPServer.udap_server_metadata(id)
+      })
+      route(:get, SMARTAppLaunch::SMART_DISCOVERY_PATH, lambda { |_env|
+        SMARTAppLaunch::MockSMARTServer.smart_server_metadata(id)
+      })
+
+      # FHIR capability statement for the simulated PAS payer server, declaring
+      # subscription support as required by the PAS IG.
+      route(:get, FHIR_METADATA_PATH, lambda { |env|
+        MockPASServer.capability_statement_response(env)
+      })
+      route(:get, SESSION_FHIR_METADATA_PATH, lambda { |env|
+        MockPASServer.capability_statement_response(env)
+      })
+
+      suite_endpoint :post, UDAPSecurityTestKit::REGISTRATION_PATH,
+                     UDAPSecurityTestKit::MockUDAPServer::RegistrationEndpoint
+      suite_endpoint :post, UDAPSecurityTestKit::TOKEN_PATH, MockUdapSmartServer::TokenEndpoint
+
+      suite_endpoint :post, SUBMIT_PATH, ClaimEndpoint
+      suite_endpoint :post, SESSION_SUBMIT_PATH, ClaimEndpoint
+      suite_endpoint :post, INQUIRE_PATH, ClaimEndpoint
+      suite_endpoint :post, SESSION_INQUIRE_PATH, ClaimEndpoint
+      suite_endpoint :post, FHIR_SUBSCRIPTION_PATH, SubscriptionCreateEndpoint
+      suite_endpoint :post, SESSION_FHIR_SUBSCRIPTION_PATH, SubscriptionCreateEndpoint
+      suite_endpoint :get, FHIR_SUBSCRIPTION_INSTANCE_PATH, SubscriptionsTestKit::SubscriptionReadEndpoint
+      suite_endpoint :get, SESSION_FHIR_SUBSCRIPTION_INSTANCE_PATH, SubscriptionsTestKit::SubscriptionReadEndpoint
+      suite_endpoint :post, FHIR_SUBSCRIPTION_INSTANCE_STATUS_PATH, SubscriptionStatusEndpoint
+      suite_endpoint :post, SESSION_FHIR_SUBSCRIPTION_INSTANCE_STATUS_PATH, SubscriptionStatusEndpoint
+      suite_endpoint :get, FHIR_SUBSCRIPTION_INSTANCE_STATUS_PATH, SubscriptionStatusEndpoint
+      suite_endpoint :get, SESSION_FHIR_SUBSCRIPTION_INSTANCE_STATUS_PATH, SubscriptionStatusEndpoint
+      suite_endpoint :post, FHIR_SUBSCRIPTION_RESOURCE_STATUS_PATH, SubscriptionStatusEndpoint
+      suite_endpoint :post, SESSION_FHIR_SUBSCRIPTION_RESOURCE_STATUS_PATH, SubscriptionStatusEndpoint
+      allow_cors UDAPSecurityTestKit::UDAP_DISCOVERY_PATH, SMARTAppLaunch::SMART_DISCOVERY_PATH,
+                 FHIR_METADATA_PATH, SESSION_FHIR_METADATA_PATH,
+                 UDAPSecurityTestKit::REGISTRATION_PATH, UDAPSecurityTestKit::TOKEN_PATH,
+                 SUBMIT_PATH, SESSION_SUBMIT_PATH, INQUIRE_PATH, SESSION_INQUIRE_PATH,
+                 FHIR_SUBSCRIPTION_PATH, SESSION_FHIR_SUBSCRIPTION_PATH,
+                 FHIR_SUBSCRIPTION_INSTANCE_PATH, SESSION_FHIR_SUBSCRIPTION_INSTANCE_PATH,
+                 FHIR_SUBSCRIPTION_INSTANCE_STATUS_PATH, SESSION_FHIR_SUBSCRIPTION_INSTANCE_STATUS_PATH,
+                 FHIR_SUBSCRIPTION_RESOURCE_STATUS_PATH, SESSION_FHIR_SUBSCRIPTION_RESOURCE_STATUS_PATH
+
+      resume_test_route :get, RESUME_PASS_PATH do |request|
+        request.query_parameters['token']
+      end
+
+      resume_test_route :get, RESUME_FAIL_PATH, result: 'fail' do |request|
+        request.query_parameters['token']
+      end
+
+      group from: :pas_client_v221_registration
+
+      # SMART test groups (with :session_url_path input removed)
+      group from: :pas_client_v221_subscription_setup, id: :pas_client_v221_subscription_setup_smart do
+        required_suite_options client_type: PASClientOptions::SMART_BACKEND_SERVICES_CONFIDENTIAL_ASYMMETRIC
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+      group from: :pas_client_v221_workflows, id: :pas_client_v221_workflows_smart do
+        required_suite_options client_type: PASClientOptions::SMART_BACKEND_SERVICES_CONFIDENTIAL_ASYMMETRIC
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+      group from: :pas_client_v221_must_support, id: :pas_client_v221_must_support_smart do
+        required_suite_options client_type: PASClientOptions::SMART_BACKEND_SERVICES_CONFIDENTIAL_ASYMMETRIC
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+      group from: :pas_client_v221_error_handling_group, id: :pas_client_v221_error_handling_smart do
+        required_suite_options client_type: PASClientOptions::SMART_BACKEND_SERVICES_CONFIDENTIAL_ASYMMETRIC
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+
+      # UDAP test groups (with :session_url_path input removed)
+      group from: :pas_client_v221_subscription_setup, id: :pas_client_v221_subscription_setup_udap do
+        required_suite_options client_type: PASClientOptions::UDAP_CLIENT_CREDENTIALS
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+      group from: :pas_client_v221_workflows, id: :pas_client_v221_workflows_udap do
+        required_suite_options client_type: PASClientOptions::UDAP_CLIENT_CREDENTIALS
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+      group from: :pas_client_v221_must_support, id: :pas_client_v221_must_support_udap do
+        required_suite_options client_type: PASClientOptions::UDAP_CLIENT_CREDENTIALS
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+      group from: :pas_client_v221_error_handling_group, id: :pas_client_v221_error_handling_udap do
+        required_suite_options client_type: PASClientOptions::UDAP_CLIENT_CREDENTIALS
+        PASClientOptions.recursive_remove_input(self, :session_url_path)
+        config(inputs: { client_id: { optional: false } })
+      end
+
+      # Dedicated Endpoints test groups (with :client_id input removed)
+      group from: :pas_client_v221_subscription_setup, id: :pas_client_v221_subscription_setup_no_auth do
+        required_suite_options client_type: PASClientOptions::OTHER_AUTH
+        PASClientOptions.recursive_remove_input(self, :client_id)
+        config(inputs: { session_url_path: { optional: false } })
+      end
+      group from: :pas_client_v221_workflows, id: :pas_client_v221_workflows_no_auth do
+        required_suite_options client_type: PASClientOptions::OTHER_AUTH
+        PASClientOptions.recursive_remove_input(self, :client_id)
+        config(inputs: { session_url_path: { optional: false } })
+      end
+      group from: :pas_client_v221_must_support, id: :pas_client_v221_must_support_no_auth do
+        required_suite_options client_type: PASClientOptions::OTHER_AUTH
+        PASClientOptions.recursive_remove_input(self, :client_id)
+        config(inputs: { session_url_path: { optional: false } })
+      end
+      group from: :pas_client_v221_error_handling_group, id: :pas_client_v221_error_handling_no_auth do
+        required_suite_options client_type: PASClientOptions::OTHER_AUTH
+        PASClientOptions.recursive_remove_input(self, :client_id)
+        config(inputs: { session_url_path: { optional: false } })
+      end
+
+      group from: :pas_client_v221_auth_smart,
+            required_suite_options: {
+              client_type: PASClientOptions::SMART_BACKEND_SERVICES_CONFIDENTIAL_ASYMMETRIC
+            }
+      group from: :pas_client_v221_auth_udap,
+            required_suite_options: {
+              client_type: PASClientOptions::UDAP_CLIENT_CREDENTIALS
+            }
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/error_handling/pas_client_operation_failure_submit_test.rb

@@ -0,0 +1,76 @@
+require_relative '../urls'
+require_relative '../../../client/client_input_descriptions'
+require_relative '../../../client/user_input_response'
+require_relative '../../../client/session_identification'
+require_relative '../../../cross_suite/tags'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    class PASClientOperationFailureSubmitTest < Inferno::Test
+      include URLs
+      include SessionIdentification
+      include UserInputResponse
+
+      id :pas_client_v221_operation_failure_submit_test
+      title 'PAS client submits a claim and receives an OperationOutcome response'
+      description %(
+        Inferno will wait for a prior authorization submission request from the client.
+        Upon receipt, Inferno will return the provided OperationOutcome with the configured
+        HTTP status code (default 400).
+      )
+
+      input :operation_failure_operation_outcome,
+            title: 'Operation Failure OperationOutcome JSON',
+            type: 'textarea',
+            description: %(
+              Inferno will return this OperationOutcome JSON in response to the $submit request
+              during this test.
+            )
+      input :operation_failure_http_status,
+            title: 'Operation Failure HTTP Status Code',
+            type: 'text',
+            optional: true,
+            default: '400',
+            description: %(
+              The HTTP status code Inferno will use when returning the OperationOutcome to the client.
+              Must be a 4XX or 5XX value. Defaults to 400 if not provided or outside that range.
+            )
+      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
+
+      submit_respond_with :operation_failure_operation_outcome
+
+      run do
+        assert_valid_json operation_failure_operation_outcome,
+                          "Input '#{input_title(:operation_failure_operation_outcome)}' must be valid JSON."
+
+        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,
+          message: %(
+            **Operation Failure Workflow Test**:
+
+            Submit a PAS request to
+
+            `#{submit_endpoint}`
+
+            Inferno will respond with the provided OperationOutcome and HTTP status
+            **#{operation_failure_http_status.present? ? operation_failure_http_status : '400'}**.
+          )
+        )
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/error_handling/pas_client_operation_outcome_validation_test.rb

@@ -0,0 +1,38 @@
+require_relative '../../../cross_suite/tags'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    class PASClientOperationOutcomeValidationTest < Inferno::Test
+      id :pas_client_v221_operation_outcome_validation_test
+      title 'Response OperationOutcome has the correct structure and content'
+      description %(
+        This test verifies the validity of the OperationOutcome returned by Inferno during the
+        Operation Failure workflow. The OperationOutcome is validated against the base FHIR R4
+        OperationOutcome resource definition — no PAS-specific profile is required.
+
+        Per IG §7.2.5, when a 4XX response is returned, an OperationOutcome SHALL be included
+        that details why the bundle could not be processed.
+      )
+      simulation_verification
+
+      run do
+        load_tagged_requests(OPERATION_FAILURE_WORKFLOW_TAG, SUBMIT_TAG)
+        skip_if requests.empty?,
+                'No responses to verify because no $submit requests were received during the Operation Failure test.'
+
+        response_body = request.response_body
+        skip_if response_body.blank?, 'The Operation Failure response body is empty.'
+
+        operation_outcome = FHIR.from_contents(response_body)
+        skip_if operation_outcome.nil?,
+                'The Operation Failure response body could not be parsed as a FHIR resource.'
+        skip_if !operation_outcome.is_a?(FHIR::OperationOutcome),
+                "Expected an OperationOutcome but received #{operation_outcome.resourceType}."
+
+        skip_if !resource_is_valid?(resource: operation_outcome),
+                'The OperationOutcome returned during the Operation Failure workflow is not conformant ' \
+                'with the base FHIR R4 OperationOutcome resource definition.'
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/error_handling/pas_client_processing_error_response_validation_test.rb

@@ -0,0 +1,55 @@
+require_relative '../../../cross_suite/pas_bundle_validation'
+require_relative '../../../client/user_input_response'
+require_relative '../../../cross_suite/tags'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    class PASClientProcessingErrorResponseValidationTest < Inferno::Test
+      include DaVinciPASTestKit::PasBundleValidation
+      include UserInputResponse
+
+      id :pas_client_v221_processing_error_response_validation_test
+      title '$submit response Bundle has the correct structure and contains error entries'
+      description %(
+        This test verifies input provided by the tester instead of the system under test.
+        Errors encountered will be treated as a skip instead of a failure.
+
+        This test verifies the conformity of the PAS Response Bundle returned by Inferno during the
+        Processing Error workflow. The bundle is validated against the
+        [PAS Response Bundle](https://hl7.org/fhir/us/davinci-pas/2.2.1/StructureDefinition-profile-pas-response-bundle.html)
+        profile. Additionally, it checks that the ClaimResponse contains at least one error entry,
+        as required by the processing error scenario.
+
+        Per IG §7.2.5, business errors that are a part of processing the 278 payload are
+        represented in the mapping to the response bundle via the ClaimResponse error capability.
+      )
+      simulation_verification
+
+      run do
+        load_tagged_requests(PROCESSING_ERROR_WORKFLOW_TAG, SUBMIT_TAG)
+        skip_if requests.empty?,
+                'No responses to verify because no $submit requests were received during the Processing Error test.'
+
+        response_body = request.response_body
+        skip_if response_body.blank?, 'The Processing Error response body is empty.'
+
+        validate_pas_bundle_json(
+          response_body,
+          'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-response-bundle',
+          '2.2.1',
+          'submit',
+          'response_bundle',
+          skips: true,
+          message: "Invalid processing error response bundle provided in 'Processing Error Response Bundle JSON' input:"
+        )
+
+        bundle = FHIR.from_contents(response_body)
+        claim_response = bundle&.entry&.find { |e| e&.resource&.resourceType == 'ClaimResponse' }&.resource
+        skip_if claim_response&.error.blank?,
+                'The ClaimResponse in the Processing Error response bundle contains no error entries. ' \
+                "The '#{input_title(:processing_error_response)}' input must include a ClaimResponse " \
+                'with at least one error entry.'
+      end
+    end
+  end
+end

data/lib/davinci_pas_test_kit/client/v2.2.1/error_handling/pas_client_processing_error_submit_test.rb

@@ -0,0 +1,67 @@
+require_relative '../urls'
+require_relative '../../../client/client_input_descriptions'
+require_relative '../../../client/user_input_response'
+require_relative '../../../client/session_identification'
+require_relative '../../../cross_suite/tags'
+
+module DaVinciPASTestKit
+  module DaVinciPASV221
+    class PASClientProcessingErrorSubmitTest < Inferno::Test
+      include URLs
+      include SessionIdentification
+      include UserInputResponse
+
+      id :pas_client_v221_processing_error_submit_test
+      title 'PAS client submits a claim and receives a response containing processing errors'
+      description %(
+        Inferno will wait for a prior authorization submission request from the client.
+        Upon receipt, Inferno will return the provided response bundle containing one or
+        more ClaimResponse.error entries.
+      )
+
+      input :processing_error_response,
+            title: 'Processing Error Response Bundle JSON',
+            type: 'textarea',
+            description: %(
+              Inferno will return this PAS Response Bundle JSON in response to the $submit request
+              during this test. The bundle must contain at least one ClaimResponse.error entry.
+            )
+      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
+
+      submit_respond_with :processing_error_response
+
+      run do
+        assert_valid_json processing_error_response,
+                          "Input '#{input_title(:processing_error_response)}' must be valid JSON."
+
+        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,
+          message: %(
+            **Processing Error Workflow Test**:
+
+            Submit a PAS request to
+
+            `#{submit_endpoint}`
+
+            Inferno will respond with the provided PAS Response Bundle containing
+            ClaimResponse.error entries.
+          )
+        )
+      end
+    end
+  end
+end