inferno_core 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fc53d7cfc20506e263bf358bba6d477fb6dff4b0523530bd2aef3d191283c28
-  data.tar.gz: aff080de4856187943390ee5478dfdd791a8962e21067be89aa7a5d40708e84c
+  metadata.gz: 77c4a279df5216b705b84640b636cb3084f27a27493668e4a57a99ab699a3ae3
+  data.tar.gz: 1d35829be39575c26962588ee44482535962be25c2dabbd7016cf727077ed3c7
 SHA512:
-  metadata.gz: b1f8fb8df13079cc0f8f9007fb1d550ec96760fe9438bc4281115c26c1a6beb55e9e7dd826f87f6dea9d4b5c97c0546cb6090fbf2370febf5c2568c333f0fda4
-  data.tar.gz: 9136dc23b84c4da21bbfd0c79cddab3d16e2aa25528a88b5636f47968aa8e801b657a1daac56f211ca0fd9c567484fcea8d1556ec8a0bc9fb206aa97ee5b8822
+  metadata.gz: a2546687c4f061eb080944bcff64dfe3aa9dc03534e808795157ad3c2b56dd6e7eee38c34821f7c5f16b551933d88acaa750d557f6c5125fe75730845d758541
+  data.tar.gz: 13681873050e6864506231c87f623007e8e09ea1ea9ae8486e703f9a4f9b417572f3c1d433ee31fe23462c3ab79c799e03d9001ed0c18f4c7ef4eb3eef8e2708

data/lib/inferno/dsl/assertions.rb

@@ -2,6 +2,10 @@ require_relative '../exceptions'
 
 module Inferno
   module DSL
+    # This module contains the assertions used within tests to verify the
+    # behavior of the systems under test. Failing an assertion causes a test to
+    # immediately stop execution and receive a `fail` result. Additional
+    # assertions added to this module will be available in all tests.
     module Assertions
       # Make an assertion
       #
@@ -159,6 +163,10 @@ module Inferno
         assert uri =~ /\A#{URI::DEFAULT_PARSER.make_regexp(['http', 'https'])}\z/, error_message
       end
 
+      # Check the Content-Type header of a response
+      #
+      # @param type [String]
+      # @param request [Inferno::Entities::Request]
       def assert_response_content_type(type, request: self.request)
         header = request.response_header('Content-Type')
         assert header.present?, no_content_type_message
@@ -166,10 +174,12 @@ module Inferno
         assert header.value.start_with?(type), bad_content_type_message(type, header.value)
       end
 
+      # @private
       def no_content_type_message
         'Response did not contain a `Content-Type` header.'
       end
 
+      # @private
       def bad_content_type_message(expected, received)
         "Expected `Content-Type` to be `#{expected}`, but found `#{received}`"
       end

data/lib/inferno/dsl/configurable.rb

@@ -2,13 +2,85 @@ require_relative '../entities/input'
 
 module Inferno
   module DSL
-    # This module contains the DSL for managing runnable configuration.
+    # This module contains the DSL for managing runnable configuration. Runnable
+    # configuration provides a way to modify test behavior at boot time.
+    #
+    # The main features enabled by configuration are:
+    # - Modifying the properties of a runnable's inputs. This could include
+    #   locking a particular input, making a particular input optional/required,
+    #   or changing an input's value.
+    # - Renaming an input/output/request to avoid name collisions when a test
+    #   suite uses the same test multiple times.
+    # - Tests can define custom configuration options to enable different
+    # - testing behavior.
+    #
+    # @example
+    #   test do
+    #     id :json_request_test
+    #
+    #     input :url
+    #     output :response_body
+    #     makes_request :json_request
+    #
+    #     run do
+    #       if config.options[:include_content_type]
+    #         get url, headers: { 'Content-Type' => 'application/json' }
+    #       else
+    #         get url
+    #       end
+    #
+    #       assert_response_status(200)
+    #       output response_body: request.response_body
+    #       assert_valid_json
+    #     end
+    #   end
+    #
+    #   group do
+    #     test from :json_request_test do
+    #       id :json_request_without_content_type
+    #
+    #       config(
+    #         inputs: {
+    #           url: { name: :url_without_content_type }
+    #         },
+    #         outputs: {
+    #           response_body: { name: :response_body_without_content_type }
+    #         },
+    #         requests: {
+    #           json_request: { name: :json_request_without_content_type }
+    #         }
+    #       )
+    #     end
+    #
+    #     test from :json_request_test do
+    #       id :json_request_with_content_type
+    #
+    #       config(
+    #         options: {
+    #           include_content_type: true
+    #         },
+    #         inputs: {
+    #           url: { name: :url_with_content_type }
+    #         },
+    #         outputs: {
+    #           response_body: { name: :response_body_with_content_type }
+    #         },
+    #         requests: {
+    #           json_request: { name: :json_request_with_content_type }
+    #         }
+    #       )
+    #     end
+    #   end
     module Configurable
       def self.extended(klass)
         klass.extend Forwardable
         klass.def_delegator 'self.class', :config
       end
 
+      # Define/update/get the configuration for a runnable. This configuration
+      # will be applied to the runnable and all of its children.
+      #
+      # @param new_configuration [Hash]
       def config(new_configuration = {})
         @config ||= Configuration.new
 
@@ -21,14 +93,18 @@ module Inferno
         @config
       end
 
-      # @private
+      # This class stores a runnable's configuration. It should never be
+      # directly instantiated within a test suite. Instead, a runnable's
+      # configuration can be modified or retrieved using the `config` method.
       class Configuration
         attr_accessor :configuration
 
+        # @private
         def initialize(configuration = {})
           self.configuration = configuration
         end
 
+        # @private
         def apply(new_configuration)
           config_to_apply =
             if new_configuration.is_a? Configuration
@@ -44,16 +120,23 @@ module Inferno
           end
         end
 
+        # The configuration options defined for this runnable.
+        #
+        # @return [Hash]
         def options
           configuration[:options] ||= {}
         end
 
         ### Input Configuration ###
 
+        # The input configuration for this runnable.
+        #
+        # @return [Hash]
         def inputs
           configuration[:inputs] ||= {}
         end
 
+        # @private
         def add_input(identifier, new_config = {})
           existing_config = input(identifier)
 
@@ -67,81 +150,103 @@ module Inferno
               .merge(Entities::Input.new(**new_config))
         end
 
+        # @private
         def default_input_params(identifier)
           { name: identifier, type: 'text' }
         end
 
+        # @private
         def input_exists?(identifier)
           inputs.key? identifier
         end
 
+        # @private
         def input(identifier)
           inputs[identifier]
         end
 
+        # @private
         def input_name(identifier)
           inputs[identifier]&.name
         end
 
+        # @private
         def input_type(identifier)
           inputs[identifier]&.type
         end
 
         ### Output Configuration ###
 
+        # The output configuration for this runnable.
+        #
+        # @return [Hash]
         def outputs
           configuration[:outputs] ||= {}
         end
 
+        # @private
         def add_output(identifier, new_config = {})
           existing_config = output_config(identifier) || {}
           outputs[identifier] = default_output_config(identifier).merge(existing_config, new_config)
         end
 
+        # @private
         def default_output_config(identifier)
           { name: identifier, type: 'text' }
         end
 
+        # @private
         def output_config_exists?(identifier)
           outputs.key? identifier
         end
 
+        # @private
         def output_config(identifier)
           outputs[identifier]
         end
 
+        # @private
         def output_name(identifier)
           outputs.dig(identifier, :name) || identifier
         end
 
+        # @private
         def output_type(identifier)
           outputs.dig(identifier, :type)
         end
 
         ### Request Configuration ###
 
+        # The request configuration for this runnable.
+        #
+        # @return [Hash]
         def requests
           configuration[:requests] ||= {}
         end
 
+        # @private
         def add_request(identifier)
           return if request_config_exists?(identifier)
 
           requests[identifier] = default_request_config(identifier)
         end
 
+        # @private
         def default_request_config(identifier)
           { name: identifier }
         end
 
+        # @private
         def request_config_exists?(identifier)
           requests.key? identifier
         end
 
+        # @private
         def request_config(identifier)
           requests[identifier]
         end
 
+        # @private
         def request_name(identifier)
           requests.dig(identifier, :name) || identifier
         end

data/lib/inferno/dsl/fhir_client.rb

@@ -34,7 +34,7 @@ module Inferno
     #       end
     #     end
     #   end
-    # @see Inferno::FHIRClientBuilder Documentation for the client
+    # @see Inferno::DSL::FHIRClientBuilder Documentation for the client
     #   configuration DSL
     module FHIRClient
       # @private
@@ -43,15 +43,13 @@ module Inferno
         klass.extend Forwardable
         klass.include RequestStorage
         klass.include TCPExceptionHandler
-
-        klass.def_delegators 'self.class', :profile_url, :validator_url
       end
 
       # Return a previously defined FHIR client
       #
       # @param client [Symbol] the name of the client
       # @return [FHIR::Client]
-      # @see Inferno::FHIRClientBuilder
+      # @see Inferno::DSL::FHIRClientBuilder
       def fhir_client(client = :default)
         fhir_clients[client] ||=
           FHIRClientBuilder.new.build(self, self.class.fhir_client_definitions[client])
@@ -101,6 +99,21 @@ module Inferno
         end
       end
 
+      # Perform a FHIR create interaction.
+      #
+      # @param resource [FHIR::Model]
+      # @param client [Symbol]
+      # @param name [Symbol] Name for this request to allow it to be used by
+      #   other tests
+      # @return [Inferno::Entities::Request]
+      def fhir_create(resource, client: :default, name: nil)
+        store_request_and_refresh_token(fhir_client(client), name) do
+          tcp_exception_handler do
+            fhir_client(client).create(resource)
+          end
+        end
+      end
+
       # Perform a FHIR read interaction.
       #
       # @param resource_type [String, Symbol, Class]
@@ -160,7 +173,7 @@ module Inferno
 
       # @todo Make this a FHIR class method? Something like
       #   FHIR.class_for(resource_type)
-      # @api private
+      # @private
       def fhir_class_from_resource_type(resource_type)
         FHIR.const_get(resource_type.to_s.camelize)
       end
@@ -168,7 +181,7 @@ module Inferno
       # This method wraps a request to automatically refresh its access token if
       # expired. It's combined with `store_request` so that all of the fhir
       # request methods don't have to be wrapped twice.
-      # @api private
+      # @private
       def store_request_and_refresh_token(client, name, &block)
         store_request('outgoing', name) do
           perform_refresh(client) if client.need_to_refresh? && client.able_to_refresh?
@@ -176,7 +189,7 @@ module Inferno
         end
       end
 
-      # @api private
+      # @private
       def perform_refresh(client)
         credentials = client.oauth_credentials
 
@@ -203,7 +216,7 @@ module Inferno
       end
 
       module ClassMethods
-        # @api private
+        # @private
         def fhir_client_definitions
           @fhir_client_definitions ||= {}
         end

data/lib/inferno/dsl/fhir_client_builder.rb

@@ -4,6 +4,22 @@ require_relative '../ext/fhir_client'
 module Inferno
   module DSL
     # DSL for configuring FHIR clients
+    #
+    # @example
+    #   input :url
+    #   input :fhir_credentials, type: :oauth_credentials
+    #   input :access_token
+    #
+    #   fhir_client do
+    #     url :url
+    #     headers 'My-Custom_header' => 'CUSTOM_HEADER_VALUE'
+    #     oauth_credentials :fhir_credentials
+    #   end
+    #
+    #   fhir_client :with_bearer_token do
+    #     url :url
+    #     bearer_token :access_token
+    #   end
     class FHIRClientBuilder
       attr_accessor :runnable
 

data/lib/inferno/dsl/http_client.rb

@@ -28,7 +28,7 @@ module Inferno
     #       end
     #     end
     #   end
-    # @see Inferno::FHIRClientBuilder Documentation for the client
+    # @see Inferno::DSL::HTTPClientBuilder Documentation for the client
     #   configuration DSL
     module HTTPClient
       # @private

data/lib/inferno/dsl/oauth_credentials.rb

@@ -2,6 +2,9 @@ require_relative '../entities/attributes'
 
 module Inferno
   module DSL
+    # OAuthCredentials provide a user with a single input which allows a fhir
+    # client to use a bearer token and automatically refresh the token when it
+    # expires.
     class OAuthCredentials
       ATTRIBUTES = [
         :access_token,
@@ -18,6 +21,16 @@ module Inferno
 
       attr_accessor :client
 
+      # @!attribute [rw] access_token
+      # @!attribute [rw] refresh_token
+      # @!attribute [rw] token_url
+      # @!attribute [rw] client_id
+      # @!attribute [rw] client_secret
+      # @!attribute [rw] token_retrieval_time
+      # @!attribute [rw] expires_in
+      # @!attribute [rw] name
+
+      # @private
       def initialize(raw_attributes_hash)
         attributes_hash = raw_attributes_hash.symbolize_keys
 
@@ -34,7 +47,7 @@ module Inferno
         self.token_retrieval_time = DateTime.now if access_token.present? && token_retrieval_time.blank?
       end
 
-      # @api private
+      # @private
       def to_hash
         self.class::ATTRIBUTES.each_with_object({}) do |attribute, hash|
           value = send(attribute)
@@ -46,12 +59,12 @@ module Inferno
         end
       end
 
-      # @api private
+      # @private
       def to_s
         JSON.generate(to_hash)
       end
 
-      # @api private
+      # @private
       def add_to_client(client)
         client.oauth_credentials = self
         self.client = client
@@ -61,7 +74,7 @@ module Inferno
         client.set_bearer_token(access_token)
       end
 
-      # @api private
+      # @private
       def need_to_refresh?
         return false if access_token.blank? || refresh_token.blank?
 
@@ -70,17 +83,17 @@ module Inferno
         token_retrieval_time.to_i + expires_in - DateTime.now.to_i < 60
       end
 
-      # @api private
+      # @private
       def able_to_refresh?
         refresh_token.present? && token_url.present?
       end
 
-      # @api private
+      # @private
       def confidential_client?
         client_id.present? && client_secret.present?
       end
 
-      # @api private
+      # @private
       def oauth2_refresh_params
         {
           'grant_type' => 'refresh_token',
@@ -88,7 +101,7 @@ module Inferno
         }
       end
 
-      # @api private
+      # @private
       def oauth2_refresh_headers
         base_headers = { 'Content-Type' => 'application/x-www-form-urlencoded' }
 
@@ -101,6 +114,7 @@ module Inferno
         )
       end
 
+      # @private
       def update_from_response_body(request)
         token_response_body = JSON.parse(request.response_body)
 

data/lib/inferno/dsl/request_storage.rb

@@ -16,7 +16,7 @@ module Inferno
 
       # Returns the most recent FHIR/HTTP request
       #
-      # @return [Inferno::Entities::Request]
+      # @return [Inferno::Entities::Request, nil]
       def request
         requests.last
       end
@@ -36,7 +36,7 @@ module Inferno
         request&.resource
       end
 
-      # TODO: do a check in the test runner
+      # @private
       def named_request(name)
         requests.find { |request| request.name == self.class.config.request_name(name.to_sym) }
       end

data/lib/inferno/dsl/results.rb

@@ -82,10 +82,12 @@ module Inferno
         raise Exceptions::WaitException, message
       end
 
+      # @private
       def identifier(identifier = nil)
         @identifier ||= identifier
       end
 
+      # @private
       def wait_timeout(timeout = nil)
         @wait_timeout ||= timeout
       end

data/lib/inferno/dsl/runnable.rb

@@ -46,6 +46,7 @@ module Inferno
       # copied, and will need to be repopulated from scratch on the new class.
       # Any child Runnable classes will themselves need to be subclassed so that
       # their parent can be updated.
+      # @private
       VARIABLES_NOT_TO_COPY = [
         :@id, # New runnable will have a different id
         :@parent, # New runnable unlikely to have the same parent
@@ -307,12 +308,6 @@ module Inferno
         @all_children ||= []
       end
 
-      def validator_url(url = nil)
-        return @validator_url ||= parent&.validator_url if url.nil?
-
-        @validator_url = url
-      end
-
       # @private
       def suite
         return self if ancestors.include? Inferno::Entities::TestSuite
@@ -397,6 +392,28 @@ module Inferno
                            (parent.user_runnable? && !parent.run_as_group?)
       end
 
+      # Set/get suite options required for this runnable to be executed.
+      #
+      # @param suite_option_requirements [Hash]
+      # @example
+      #   suite_option :ig_version,
+      #               list_options: [
+      #                 {
+      #                   label: 'IG v1',
+      #                   value: 'ig_v1'
+      #                 },
+      #                 {
+      #                   label: 'IG v2',
+      #                   value: 'ig_v2'
+      #                 }
+      #               ]
+      #
+      #   group from: :ig_v1_group,
+      #         required_suite_options: { ig_version: 'ig_v1' }
+      #
+      #   group from: :ig_v2_group do
+      #     required_suite_options ig_version: 'ig_v2'
+      #   end
       def required_suite_options(suite_option_requirements)
         @suite_option_requirements =
           suite_option_requirements.map do |key, value|
@@ -404,6 +421,7 @@ module Inferno
           end
       end
 
+      # @private
       def children(selected_suite_options = [])
         return all_children if selected_suite_options.blank?
 
@@ -417,6 +435,16 @@ module Inferno
           end
         end
       end
+
+      def inspect
+        non_dynamic_ancestor = ancestors.find { |ancestor| !ancestor.to_s.start_with? '#' }
+        "#<#{non_dynamic_ancestor}".tap do |inspect_string|
+          inspect_string.concat(" @id=#{id.inspect},")
+          inspect_string.concat(" @short_id=#{short_id.inspect},") if respond_to? :short_id
+          inspect_string.concat(" @title=#{title.inspect}")
+          inspect_string.concat('>')
+        end
+      end
     end
   end
 end

data/lib/inferno/dsl/suite_option.rb

@@ -2,6 +2,11 @@ require_relative '../entities/attributes'
 
 module Inferno
   module DSL
+    # This class is used to represent TestSuite-level options which are selected
+    # by the user, and can affect which tests/groups are displayed and run as
+    # well as the behavior of those tests.
+    #
+    # @see Inferno::Entities::TestSuite.suite_option
     class SuiteOption
       ATTRIBUTES = [
         :id,
@@ -13,6 +18,13 @@ module Inferno
 
       include Entities::Attributes
 
+      # @!attribute [rw] id
+      # @!attribute [rw] title
+      # @!attribute [rw] description
+      # @!attribute [rw] list_options
+      # @!attribute [rw] value
+
+      # @private
       def initialize(raw_params)
         params = raw_params.deep_symbolize_keys
         bad_params = params.keys - ATTRIBUTES
@@ -26,10 +38,12 @@ module Inferno
         self.id = id.to_sym if id.is_a? String
       end
 
+      # @private
       def ==(other)
         id == other.id && value == other.value
       end
 
+      # @private
       def to_hash
         self.class::ATTRIBUTES.each_with_object({}) do |attribute, hash|
           hash[attribute] = send(attribute)

data/lib/inferno/dsl/tcp_exception_handler.rb

@@ -1,5 +1,6 @@
 module Inferno
   module DSL
+    # @private
     module TCPExceptionHandler
       def tcp_exception_handler(&block)
         block.call

data/lib/inferno/entities/attributes.rb

@@ -1,5 +1,6 @@
 module Inferno
   module Entities
+    # @private
     module Attributes
       def self.included(klass)
         klass.attr_accessor(*klass::ATTRIBUTES)

data/lib/inferno/entities/request.rb

@@ -42,6 +42,7 @@ module Inferno
 
       include Attributes
 
+      # @private
       def initialize(params)
         super(params, ATTRIBUTES - [:headers, :name])
 
@@ -86,7 +87,8 @@ module Inferno
 
       # Return a hash of the request parameters
       #
-      # @return [Hash]
+      # @return [Hash] A Hash with `:verb`, `:url`, `:headers`, and `:body`
+      #   fields
       def request
         {
           verb:,
@@ -98,7 +100,7 @@ module Inferno
 
       # Return a hash of the response parameters
       #
-      # @return [Hash]
+      # @return [Hash] A Hash with `:status`, `:headers`, and `:body` fields
       def response
         {
           status:,

data/lib/inferno/entities/test.rb

@@ -47,7 +47,7 @@ module Inferno
         end
       end
 
-      # @api private
+      # @private
       # A hash containing outputs that have been set during execution and need
       # to be persisted. A test may not always update all outputs, so this is
       # used to prevent overwriting an output with nil when it wasn't updated.