us_core_test_kit 0.11.2 → 0.11.3

data/lib/us_core_test_kit/client/generator/group_generator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../../generator/group_generator'
+require_relative '../../generator/naming'
+require_relative '../../generator/special_cases'
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class GroupGenerator < USCoreTestKit::Generator::GroupGenerator
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'group.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def class_name
+          "#{profile_identifier.camelize}ClientGroup"
+        end
+
+        def module_name
+          "USCoreClient#{group_metadata.reformatted_version.upcase}"
+        end
+
+        def group_id
+          "us_core_client_#{group_metadata.reformatted_version}_#{profile_identifier}"
+        end
+
+        def description
+          <<~DESCRIPTION
+
+            # Background
+
+            This test group verifies that the client under test is
+            able to perform the required #{resource_type} queries.
+
+            # Testing Methodology
+
+            ## Reading
+            This sequence will check that the client performed a search with the following ID:
+
+            * `us-core-client-tests-#{profile_identifier.underscore.dasherize}`
+
+            ## Searching
+            This sequence will check that the client performed searches with the following parameters:
+
+            #{search_param_name_string}
+          DESCRIPTION
+        end
+
+        def generate
+          File.write(output_file_name, output)
+          group_metadata.id = group_id
+          group_metadata.file_name = base_output_file_name
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/read_endpoint_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class ReadEndpointGenerator
+        class << self
+          def generate(ig_metadata, base_output_dir)
+            new(ig_metadata, base_output_dir).generate
+          end
+        end
+
+        attr_accessor :ig_metadata, :base_output_dir
+
+        def initialize(ig_metadata, base_output_dir)
+          self.ig_metadata = ig_metadata
+          self.base_output_dir = base_output_dir
+        end
+
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'read_endpoint.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def base_output_file_name
+          'read_endpoint.rb'
+        end
+
+        def module_name
+          "USCoreClient#{ig_metadata.reformatted_version.upcase}"
+        end
+
+        def output_file_name
+          File.join(base_output_dir, base_output_file_name)
+        end
+
+        def groups
+          ig_metadata.ordered_groups
+            .reject { |group| USCoreTestKit::Generator::SpecialCases.exclude_group? group }
+        end
+
+        def resources
+          groups.map { |group| group.resource }.uniq
+        end
+
+        def generate
+          File.write(output_file_name, output)
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/read_test_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative '../../generator/read_test_generator'
+require_relative '../../generator/naming'
+require_relative '../../generator/special_cases'
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class ReadTestGenerator < USCoreTestKit::Generator::ReadTestGenerator
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'read_test.rb.erb'))
+        end
+
+        def group_name
+          "#{profile_identifier.camelize}ClientGroup"
+        end
+
+        def class_name
+          "#{profile_identifier.camelize}ClientReadTest"
+        end
+
+        def module_name
+          "USCoreClient#{group_metadata.reformatted_version.upcase}"
+        end
+
+        def test_id
+          "us_core_#{group_metadata.reformatted_version}_#{class_name.underscore}"
+        end
+
+        def resource
+          group_metadata.resource
+        end
+
+        def expected_resource_id
+          "us-core-client-tests-#{profile_identifier.underscore.dasherize}"
+        end
+
+        def title
+          "#{conformance_expectation} support read of #{profile_identifier.camelize}"
+        end
+
+        def description
+          "The client demonstrates #{conformance_expectation} support for reading #{profile_identifier.camelize}."
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/registration_configuration_display_test_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class RegistrationConfigurationDisplayTestGenerator
+        class << self
+          def generate(ig_metadata, base_output_dir, protocol)
+            new(ig_metadata, base_output_dir, protocol).generate
+          end
+        end
+
+        attr_accessor :ig_metadata, :base_output_dir, :protocol
+
+        def initialize(ig_metadata, base_output_dir, protocol)
+          self.ig_metadata = ig_metadata
+          self.base_output_dir = base_output_dir
+          self.protocol = protocol
+        end
+
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'registration_configuration_display_test.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def version
+          ig_metadata.reformatted_version.downcase
+        end
+
+        def base_output_file_name
+          "configuration_display_#{protocol.downcase}_test.rb"
+        end
+
+        def module_name
+          "USCoreClient#{ig_metadata.reformatted_version.upcase}"
+        end
+
+        def output_file_name
+          File.join(base_output_dir, 'registration', base_output_file_name)
+        end
+
+        def generate
+          File.write(output_file_name, output)
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/registration_group_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class RegistrationGroupGenerator
+        class << self
+          def generate(ig_metadata, base_output_dir)
+            new(ig_metadata, base_output_dir).generate
+          end
+        end
+
+        attr_accessor :ig_metadata, :base_output_dir
+
+        def initialize(ig_metadata, base_output_dir)
+          self.ig_metadata = ig_metadata
+          self.base_output_dir = base_output_dir
+        end
+
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'registration_group.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def version
+          ig_metadata.reformatted_version.downcase
+        end
+
+        def base_output_file_name
+          "registration_group.rb"
+        end
+
+        def module_name
+          "USCoreClient#{ig_metadata.reformatted_version.upcase}"
+        end
+
+        def output_file_name
+          File.join(base_output_dir, base_output_file_name)
+        end
+
+        def generate
+          File.write(output_file_name, output)
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/search_endpoint_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class SearchEndpointGenerator
+        class << self
+          def generate(ig_metadata, base_output_dir)
+            new(ig_metadata, base_output_dir).generate
+          end
+        end
+
+        attr_accessor :ig_metadata, :base_output_dir
+
+        def initialize(ig_metadata, base_output_dir)
+          self.ig_metadata = ig_metadata
+          self.base_output_dir = base_output_dir
+        end
+
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'search_endpoint.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def base_output_file_name
+          'search_endpoint.rb'
+        end
+
+        def module_name
+          "USCoreClient#{ig_metadata.reformatted_version.upcase}"
+        end
+
+        def output_file_name
+          File.join(base_output_dir, base_output_file_name)
+        end
+
+        def groups
+          ig_metadata.ordered_groups
+            .reject { |group| USCoreTestKit::Generator::SpecialCases.exclude_group? group }
+        end
+
+        def resources
+          groups.map { |group| group.resource }.uniq
+        end
+
+        def generate
+          File.write(output_file_name, output)
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/search_test_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../../generator/search_test_generator'
+require_relative '../../generator/naming'
+require_relative '../../generator/special_cases'
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class SearchTestGenerator < USCoreTestKit::Generator::SearchTestGenerator
+        class << self
+          def generate(ig_metadata, base_output_dir)
+            ig_metadata.groups
+                       .reject { |group| USCoreTestKit::Generator::SpecialCases.exclude_group? group }
+                       .select { |group| group.searches.present? }
+                       .each do |group|
+              group.searches.each do |search|
+                next unless search[:expectation] == 'SHALL'
+
+                new(group, search, base_output_dir).generate
+              end
+            end
+          end
+        end
+
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'search_test.rb.erb'))
+        end
+
+        def group_name
+          "#{profile_identifier.camelize}ClientGroup"
+        end
+
+        def class_name
+          "#{profile_identifier.camelize}#{search_identifier.camelize}ClientSearchTest"
+        end
+
+        def resource
+          group_metadata.resource
+        end
+
+        def module_name
+          "USCoreClient#{group_metadata.reformatted_version.upcase}"
+        end
+
+        def test_id
+          "us_core_#{group_metadata.reformatted_version}_#{class_name.underscore}"
+        end
+
+        def title
+          "#{conformance_expectation} support #{search_param_name_string} search of #{profile_identifier.camelize}"
+        end
+
+        def description
+          "The client demonstrates #{conformance_expectation} support for searching #{search_param_name_string} on #{profile_identifier.camelize}."
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/suite_generator.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative '../../generator/suite_generator'
+require_relative '../../generator/special_cases'
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class SuiteGenerator < USCoreTestKit::Generator::SuiteGenerator
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'suite.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def base_output_file_name
+          'us_core_client_test_suite.rb'
+        end
+
+        def class_name
+          'USCoreClientTestSuite'
+        end
+
+        def module_name
+          "USCoreClient#{ig_metadata.reformatted_version.upcase}"
+        end
+
+        def group_ids
+          groups
+            .map do |group|
+              "#{USCoreTestKit::Generator::Naming.snake_case_for_profile(group)}ClientGroup".underscore
+            end
+        end
+
+        def group_names
+          group_ids.map(&:camelize)
+        end
+
+        def suite_id
+          "us_core_client_#{ig_metadata.reformatted_version}"
+        end
+
+        def title
+          "US Core Client #{ig_metadata.ig_version}"
+        end
+
+        def description
+          <<~DESCRIPTION
+
+            The US Core Test Kit Client Suite tests client systems for their conformance
+            to the US Core Implementation Guide.
+
+            # Scope
+
+            These tests are a DRAFT intended to allow implementers to perform preliminary checks
+            of their client systems against the requirements stated for US Core Implementation
+            Guide and provide feedback on the tests. Future versions of these tests may verify other
+            requirements and may change the test verification logic.
+
+            # Test Methodology
+
+            For these tests Inferno simulates the FHIR server. Inferno's simulated server contains
+            data for each of the following US Core Profiles:
+
+            #{profiles_description}
+
+            During execution, Inferno will wait for the client under test to issue requests and will
+            respond to them with the requested data. Inferno will then evaluate the requests in aggregate
+            to verify that they demonstrate that the client:
+
+            * Retrieved instances of each profile
+            * Performed searches using the required search parameters and search parameter combinations
+
+            # Running the Tests
+
+            ## Quick Start
+
+            Inferno's simulated US Core endpoints require authentication using the OAuth flows
+            conforming to one of the following:
+            - SMART [App Launch flow](https://hl7.org/fhir/smart-app-launch/STU2.2/app-launch.html), or
+            - UDAP [Consumer-Facing flow](https://hl7.org/fhir/us/udap-security/STU1/consumer.html).
+
+            When creating a test session, select the Client Security Type corresponding to an
+            authentication approach supported by the client. Then, start by running the "Client Registration"
+            group which will guide you through the registration process, including what inputs to provide.
+            See the *Auth Configuration Details* section below for details.
+
+            Once registration is complete, run the "Read & Search" group to have Inferno wait for US Core
+            read and search requests from the client, return the requested US Core
+            resources to the client, and verify the interactions. The Patient that the client
+            needs to request data for has the following demographic details:
+            - **Resource ID**: us-core-client-tests-patient
+            - **Name**: ClientTests USCore
+            - **Member Identifier**: us-core-client-tests-patient (system: Inferno)
+            - **Date of Birth**: 1940-03-29
+            - **Gender**: male
+
+            ## Demonstration
+
+            To try out these tests without an actual US Core client implementation, you may run them against
+            the US Core Server tests using the following steps:
+
+            1. In separate tabs, create test sessions for corresponding versions of
+               - The "US Core" test suite, choosing the "SMART App Launch 2.2.0" option
+               - The "US Core Client" test suite, choosing the "SMART App Launch Public Client" option
+            2. In the US Core Client test session, select the "Demo: Run Against the US Core Server Suite"
+               preset in the upper left, click the "RUN ALL TESTS" button in the upper right, and then click
+               "SUBMIT" at the bottom of the input dialog that appears. Confirm the configuration of the client
+               by clicking the link in the first "User Action Required" dialog that appears, so that a second
+               one appears asking for US Core requests to be made.
+            3. In the US Core Server test session, select the "Standalone Launch" group from the list
+               at the left, select the "Demo: Run Against the US Core Client Suite"
+               preset in the upper left, click the "RUN TESTS" button in the upper right, and then click
+               "SUBMIT" at the bottom of the input dialog that appears. When a "User Action Required" dialog
+               appears, click the link to authorize with the server and the test run will complete. A few tests
+               may fail.
+            4. Select the "US Core FHIR API" group from the list at the left, click the "RUN ALL TESTS" button
+               in the upper right, and then click "SUBMIT" at the bottom of the input dialog that appears.
+               These tests will run for a while and may result in test failures around must support and
+               conformance features.
+            5. Once the server tests have completed, return to the client test session and click the link
+               in the "User Action Required" dialog to continue the tests and evaluate the client's
+               interactions. These tests will also run for a while and may result in some failures.
+
+            # Input Details
+
+            ## Auth Configuration Details
+
+            When running these tests there are 4 options for authentication, which also allows
+            Inferno to identify which session the requests are for. The choice is made when the
+            session is created with the selected Client Security Type option, which determines
+            what details the tester needs to provide during the Client Registration tests:
+
+            - **SMART App Launch Client**: the system under test will manually register
+              with Inferno and request access tokens to use when accessing FHIR endpoints
+              as per the SMART App Luanch specification, which includes providing one or more
+              redirect URI(s) in the **SMART App Launch Redirect URI(s)** input, and optionally,
+              launch URL(s) in the **SMART App Launch URL(s)** input. Additionally, testers may provide
+              a **Client Id** if they want their client assigned a specific one. Depending on the
+              specific SMART flavor chosen, additional inputs for authentication may be needed:
+              - **SMART App Launch Public Client**: no additional authentication inputs
+              - **SMART App Launch Confidential Symmetric Client**: provide a secret using the
+                **SMART Confidential Symmetric Client Secret** input.
+              - **SMART App Launch Confidential Asymmetric Client**: provide a URL that resolves
+                to a JWKS or a raw JWKS in JSON format using the **SMART JSON Web Key Set (JWKS)** input.
+            - **UDAP Authorization Code Client**: the system under test will dynamically register
+              with Inferno and request access tokens used to access FHIR endpoints
+              as per the UDAP specification. It requires the **UDAP Client URI** input
+              to be populated with the URI that the client will use when dynamically
+              registering with Inferno. This will be used to generate a client id (each
+              unique UDAP Client URI will always get the same client id). All other details
+              that Inferno needs will be provided as a part of the dynamic registration.
+
+            ## Inputs Controlling Token Responses
+
+            Inferno's SMART simulation does not include the details needed to populate
+            the token response [context data](https://hl7.org/fhir/smart-app-launch/STU2.2/scopes-and-launch-context.html)
+            when requested by apps using scopes during the *SMART App Launch* flow. If the tested app
+            needs and will request these details, the tester must provide them for Inferno
+            to respond with using the following inputs:
+            - **Launch Context**: Testers can provide a JSON
+              array for Inferno to use as the base for building a token response on. This can include
+              keys like `"patient"` when the `launch/patient` scope will be requested. Note that when keys that Inferno
+              also populates (e.g. `access_token` or `id_token`) are included, the Inferno value will be returned.
+            - **FHIR User Relative Reference**: Testers
+              can provide a FHIR relative reference (`<resource type>/<id>`) for the FHIR user record
+              to return with the `id_token` when the `openid` and `fhirUser` scopes are requested.
+              If populated, ensure that the referenced resource is available in Inferno's simulated
+              FHIR server so that it can be accessed.
+
+            # Current Limitations
+
+            This test suite is still in draft form and does not test all of the client requirements and features
+            described in the US Core Implementation guide.
+
+            The current version of this test suite supports:
+            - Testing a client's ability to perform read requests against a FHIR server for all US Core Profiles
+            summarized in the US Core Capability Statement.
+            - Testing a client's ability to perform searches using the SHALL conformance search parameters
+            summarized in the US Core Capability Statement.
+
+            The current version of this test suite does not support:
+            - Testing searches with/via:
+              - date comparator
+              - multiple-OR
+              - _revInclude
+              - The client SHALL provide values precise to the day for elements of datatype date and to the second + time offset for elements of datatype dateTime.
+            - The Must Support Conformance Requirements for clients/requestors specified in US Core IG #{ig_metadata.ig_version}
+            - Clients that cannot follow the SMART App Launch or UDAP Consumer-Facing OAuth flows to obtain an access token.
+
+          DESCRIPTION
+        end
+
+        def profiles_description
+          groups
+            .map do |group|
+              profile = USCoreTestKit::Generator::Naming.snake_case_for_profile(group)
+              "* **#{profile.camelize}**\n  * id: us-core-client-tests-#{profile.underscore.dasherize}"
+            end
+            .join("\n")
+        end
+
+        def wait_group_id
+          "us_core_client_wait_group_#{ig_metadata.reformatted_version.downcase}"
+        end
+
+        def registration_group_id
+          "us_core_client_#{ig_metadata.reformatted_version.downcase}_registration"
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/tags_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module USCoreTestKit
+  module Client
+    class Generator
+      class TagsGenerator
+        class << self
+          def generate(ig_metadata, base_output_dir)
+            new(ig_metadata, base_output_dir).generate
+          end
+        end
+
+        attr_accessor :ig_metadata, :base_output_dir
+
+        def initialize(ig_metadata, base_output_dir)
+          self.ig_metadata = ig_metadata
+          self.base_output_dir = base_output_dir
+        end
+
+        def module_name
+          "USCoreClient#{ig_metadata.reformatted_version.upcase}"
+        end
+
+        def template
+          @template ||= File.read(File.join(__dir__, 'templates', 'tags.rb.erb'))
+        end
+
+        def output
+          @output ||= ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        def base_output_file_name
+          'tags.rb'
+        end
+
+        def groups
+          ig_metadata.ordered_groups
+            .reject { |group| USCoreTestKit::Generator::SpecialCases.exclude_group? group }
+        end
+
+        def resources
+          groups.map { |group| group.resource }.uniq
+        end
+
+        def output_file_name
+          File.join(base_output_dir, base_output_file_name)
+        end
+
+        def generate
+          File.write(output_file_name, output)
+        end
+      end
+    end
+  end
+end

data/lib/us_core_test_kit/client/generator/templates/auth_smart_group.rb.erb

@@ -0,0 +1,30 @@
+require 'smart_app_launch_test_kit'
+require_relative 'tags'
+
+module USCoreTestKit
+  module Client
+    module <%= module_name %>
+      class AuthSMART<%= authentication_approach %>Group < Inferno::TestGroup
+        id :us_core_client_<%= version %>_auth_smart_<%= client_type_abbreviation %>
+        title 'Review Authentication Interactions'
+        description %(
+          During these tests, Inferno will verify that the client interacted with Inferno's
+          simulated SMART authorization server in a conformant manner when requesting access tokens
+          and that the client under test was able to use provided access tokens to make US Core
+          requests.
+        )
+        run_as_group
+
+        # smart auth verification
+        test from: :smart_client_authorization_request_verification,
+            id: :us_core_client_<%= version %>_authorization_smart_<%= client_type_abbreviation %>_verification,
+            config: { options: { endpoint_suite_id: :us_core_client_<%= version %> } }
+        test from: :smart_client_token_request_<%= client_type_abbreviation %>_verification,
+            id: :us_core_client_<%= version %>_token_smart_<%= client_type_abbreviation %>_verification,
+            config: { options: { endpoint_suite_id: :us_core_client_<%= version %> } }
+        test from: :smart_client_token_use_verification,
+            config: { options: { access_request_tags: [READ_REQUEST_TAG, SEARCH_REQUEST_TAG] } }
+      end
+    end
+  end
+end