inferno_core 0.0.5 → 0.0.8.pre2

data/lib/inferno/dsl/fhir_validation.rb

@@ -1,38 +1,113 @@
 module Inferno
   module DSL
+    # This module contains the methods needed to configure a validator to
+    # perform validation of FHIR resources. The actual validation is performed
+    # by an external FHIR validation service. Tests will typically rely on
+    # `assert_valid_resource` for validation rather than directly calling
+    # methods on a validator.
+    #
+    # @example
+    #
+    #   validator do
+    #     url 'http://example.com/validator'
+    #     exclude_message { |message| message.type == 'info' }
+    #     perform_additional_validation do |resource, profile_url|
+    #       if something_is_wrong
+    #         { type: 'error', message: 'something is wrong' }
+    #       else
+    #         { type: 'info', message: 'everything is ok' }
+    #       end
+    #     end
+    #   end
     module FHIRValidation
       def self.included(klass)
         klass.extend ClassMethods
       end
 
+      # Perform validation, and add validation messages to the runnable
+      #
+      # @param resource [FHIR::Model]
+      # @param profile_url [String]
+      # @param validator [Symbol] the name of the validator to use
+      # @return [Boolean] whether the resource is valid
       def resource_is_valid?(resource: self.resource, profile_url: nil, validator: :default)
         find_validator(validator).resource_is_valid?(resource, profile_url, self)
       end
 
+      # Find a particular validator. Looks through a runnable's parents up to
+      # the suite to find a validator with a particular name
       def find_validator(validator_name)
         self.class.find_validator(validator_name)
       end
 
       class Validator
+        # @private
         def initialize(&block)
           instance_eval(&block)
         end
 
+        # @private
         def default_validator_url
           ENV.fetch('VALIDATOR_URL')
         end
 
+        # Set the url of the validator service
+        #
+        # @param url [String]
         def url(validator_url = nil)
           @url = validator_url if validator_url
 
           @url
         end
 
+        # @private
+        def additional_validations
+          @additional_validations ||= []
+        end
+
+        # Perform validation steps in addition to FHIR validation.
+        #
+        # @example
+        #   perform_additional_validation do |resource, profile_url|
+        #     if something_is_wrong
+        #       { type: 'error', message: 'something is wrong' }
+        #     else
+        #       { type: 'info', message: 'everything is ok' }
+        #     end
+        #   end
+        # @yieldparam resource [FHIR::Model] the resource being validated
+        # @yieldparam profile_url [String] the profile the resource is being
+        #   validated against
+        # @yieldreturn [Array<Hash<Symbol, String>>,Hash<Symbol, String>] The
+        #   block should return a Hash or an Array of Hashes if any validation
+        #   messages should be added. The Hash must contain two keys: `:type`
+        #   and `:message`. `:type` can have a value of `'info'`, `'warning'`,
+        #   or `'error'`. A type of `'error'` means the resource is invalid.
+        #   `:message` contains the message string itself.
+        def perform_additional_validation(&block)
+          additional_validations << block
+        end
+
+        # @private
+        def additional_validation_messages(resource, profile_url)
+          additional_validations
+            .flat_map { |step| step.call(resource, profile_url) }
+            .select { |message| message.is_a? Hash }
+        end
+
+        # Filter out unwanted validation messages
+        #
+        # @example
+        #   validator do
+        #     exclude_message { |message| message.type == 'info' }
+        #   end
+        # @yieldparam message [Inferno::Entities::Message]
         def exclude_message(&block)
           @exclude_message = block if block_given?
           @exclude_message
         end
 
+        # @see Inferno::DSL::FHIRValidation#resource_is_valid?
         def resource_is_valid?(resource, profile_url, runnable)
           profile_url ||= FHIR::Definitions.resource_definition(resource.resourceType).url
 
@@ -40,6 +115,8 @@ module Inferno
 
           message_hashes = outcome.issue&.map { |issue| message_hash_from_issue(issue) } || []
 
+          message_hashes.concat(additional_validation_messages(resource, profile_url))
+
           filter_messages(message_hashes)
 
           message_hashes
@@ -47,10 +124,12 @@ module Inferno
             .none? { |message_hash| message_hash[:type] == 'error' }
         end
 
+        # @private
         def filter_messages(message_hashes)
           message_hashes.reject! { |message| exclude_message.call(Entities::Message.new(message)) } if exclude_message
         end
 
+        # @private
         def message_hash_from_issue(issue)
           {
             type: issue_severity(issue),
@@ -58,6 +137,7 @@ module Inferno
           }
         end
 
+        # @private
         def issue_severity(issue)
           case issue.severity
           when 'warning'
@@ -69,6 +149,7 @@ module Inferno
           end
         end
 
+        # @private
         def issue_message(issue)
           location = if issue.respond_to?(:expression)
                        issue.expression&.join(', ')
@@ -79,6 +160,11 @@ module Inferno
           "#{location}: #{issue&.details&.text}"
         end
 
+        # Post a resource to the validation service for validating.
+        #
+        # @param resource [FHIR::Model]
+        # @param profile_url [String]
+        # @return [String] the body of the validation response
         def validate(resource, profile_url)
           RestClient.post(
             "#{url}/validate",
@@ -89,15 +175,33 @@ module Inferno
       end
 
       module ClassMethods
-        # @api private
+        # @private
         def fhir_validators
           @fhir_validators ||= {}
         end
 
+        # Define a validator
+        # @example
+        #   validator do
+        #     url 'http://example.com/validator'
+        #     exclude_message { |message| message.type == 'info' }
+        #     perform_additional_validation do |resource, profile_url|
+        #       if something_is_wrong
+        #         { type: 'error', message: 'something is wrong' }
+        #       else
+        #         { type: 'info', message: 'everything is ok' }
+        #       end
+        #     end
+        #   end
+        #
+        # @param name [Symbol] the name of the validator, only needed if you are
+        #   using multiple validators
         def validator(name = :default, &block)
           fhir_validators[name] = Inferno::DSL::FHIRValidation::Validator.new(&block)
         end
 
+        # Find a particular validator. Looks through a runnable's parents up to
+        # the suite to find a validator with a particular name
         def find_validator(validator_name)
           validator = fhir_validators[validator_name] || parent&.find_validator(validator_name)
 

data/lib/inferno/dsl/http_client.rb

@@ -16,7 +16,7 @@ module Inferno
     #         # performs a GET to https://example.com
     #         get
     #         # performs a GET to https://example.com/abc
-    #          get('abc')
+    #         get('abc')
     #
     #         request  # the most recent request
     #         response # the most recent response
@@ -27,7 +27,7 @@ module Inferno
     # @see Inferno::FHIRClientBuilder Documentation for the client
     #   configuration DSL
     module HTTPClient
-      # @api private
+      # @private
       def self.included(klass)
         klass.extend ClassMethods
         klass.include RequestStorage
@@ -47,7 +47,7 @@ module Inferno
         http_clients[client] = HTTPClientBuilder.new.build(self, definition)
       end
 
-      # @api private
+      # @private
       def http_clients
         @http_clients ||= {}
       end
@@ -60,16 +60,17 @@ module Inferno
       # @param client [Symbol]
       # @param name [Symbol] Name for this request to allow it to be used by
       #   other tests
-      # @param _options [Hash] TODO
+      # @option options [Hash] Input headers here - headers are optional and
+      #   must be entered as the last piece of input to this method
       # @return [Inferno::Entities::Request]
-      def get(url = '', client: :default, name: nil, **_options)
+      def get(url = '', client: :default, name: nil, **options)
         store_request('outgoing', name) do
           client = http_client(client)
 
           if client
-            client.get(url)
+            client.get(url, nil, options[:headers])
           elsif url.match?(%r{\Ahttps?://})
-            Faraday.get(url)
+            Faraday.get(url, nil, options[:headers])
           else
             raise StandardError, 'Must use an absolute url or define an HTTP client with a base url'
           end
@@ -85,16 +86,17 @@ module Inferno
       # @param client [Symbol]
       # @param name [Symbol] Name for this request to allow it to be used by
       #   other tests
-      # @param _options [Hash] TODO
+      # @option options [Hash] Input headers here - headers are optional and
+      #   must be entered as the last piece of input to this method
       # @return [Inferno::Entities::Request]
-      def post(url = '', body: nil, client: :default, name: nil, **_options)
+      def post(url = '', body: nil, client: :default, name: nil, **options)
         store_request('outgoing', name) do
           client = http_client(client)
 
           if client
-            client.post(url, body)
+            client.post(url, body, options[:headers])
           elsif url.match?(%r{\Ahttps?://})
-            Faraday.post(url, body)
+            Faraday.post(url, body, options[:headers])
           else
             raise StandardError, 'Must use an absolute url or define an HTTP client with a base url'
           end
@@ -102,7 +104,7 @@ module Inferno
       end
 
       module ClassMethods
-        # @api private
+        # @private
         def http_client_definitions
           @http_client_definitions ||= {}
         end

data/lib/inferno/dsl/http_client_builder.rb

@@ -4,7 +4,7 @@ module Inferno
     class HTTPClientBuilder
       attr_accessor :runnable
 
-      # @api private
+      # @private
       def build(runnable, block)
         self.runnable = runnable
         instance_exec(self, &block)
@@ -38,14 +38,14 @@ module Inferno
         @headers ||= headers
       end
 
-      # @api private
+      # @private
       def method_missing(name, *args, &block)
         return runnable.call(name, *args, &block) if runnable.respond_to? name
 
         super
       end
 
-      # @api private
+      # @private
       def respond_to_missing?(name)
         runnable.respond_to?(name) || super
       end

data/lib/inferno/dsl/request_storage.rb

@@ -38,13 +38,14 @@ module Inferno
 
       # TODO: do a check in the test runner
       def named_request(name)
-        requests.find { |request| request.name == name.to_sym }
+        requests.find { |request| request.name == self.class.config.request_name(name.to_sym) }
       end
 
-      # @api private
+      # @private
       def store_request(direction, name = nil, &block)
         response = block.call
 
+        name = self.class.config.request_name(name)
         request =
           if response.is_a? FHIR::ClientReply
             Entities::Request.from_fhir_client_reply(
@@ -60,52 +61,60 @@ module Inferno
         request
       end
 
-      # @api private
+      # @private
       def load_named_requests
         requests_repo = Inferno::Repositories::Requests.new
         self.class.named_requests_used.map do |request_name|
-          request = requests_repo.find_named_request(test_session_id, request_name)
-          raise StandardError, "Unable to find '#{request_name}' request" if request.nil?
+          request_alias = self.class.config.request_name(request_name)
+          request = requests_repo.find_named_request(test_session_id, request_alias)
+          raise StandardError, "Unable to find '#{request_alias}' request" if request.nil?
 
           requests << request
         end
       end
 
       module ClassMethods
-        # @api private
+        # @private
         def named_requests_made
           @named_requests_made ||= []
         end
 
-        # @api private
+        # @private
         def named_requests_used
           @named_requests_used ||= []
         end
 
         # Specify the named requests made by a test
         #
-        # @param *names [Symbol] one or more Symbols
-        def makes_request(*names)
-          named_requests_made.concat(names)
+        # @param identifiers [Symbol] one or more request identifiers
+        def makes_request(*identifiers)
+          named_requests_made.concat(identifiers).uniq!
+          identifiers.each do |identifier|
+            config.add_request(identifier)
+          end
         end
 
         # Specify the name for a request received by a test
         #
-        # @param *names [Symbol] one or more Symbols
-        def receives_request(name)
-          @incoming_request_name = name
+        # @param identifier [Symbol]
+        def receives_request(identifier)
+          config.add_request(identifier)
+          @incoming_request_name = identifier
         end
 
-        # @api private
+        # @private
         def incoming_request_name
           @incoming_request_name
         end
 
         # Specify the named requests used by a test
         #
-        # @param *names [Symbol] one or more Symbols
-        def uses_request(*names)
-          named_requests_used.concat(names)
+        # @param identifiers [Symbol] one or more request identifiers
+        def uses_request(*identifiers)
+          named_requests_used.concat(identifiers).uniq!
+          identifiers.each do |identifier|
+            config.add_request(identifier)
+          end
         end
       end
     end

data/lib/inferno/dsl/results.rb

@@ -94,7 +94,7 @@ module Inferno
       # and should not be used in real tests.
       #
       # @param message [String]
-      # @api private
+      # @private
       def cancel(message = '')
         raise Exceptions::CancelException, message
       end

data/lib/inferno/dsl/resume_test_route.rb

@@ -4,7 +4,7 @@ module Inferno
   module DSL
     # A base class for creating routes to resume test execution upon receiving
     # an incoming request.
-    # @api private
+    # @private
     # @see Inferno::DSL::Runnable#resume_test_route
     class ResumeTestRoute
       include Hanami::Action
@@ -26,49 +26,49 @@ module Inferno
         @request ||= Inferno::Entities::Request.from_rack_env(@params.env)
       end
 
-      # @api private
+      # @private
       def test_run
         @test_run ||=
           test_runs_repo.find_latest_waiting_by_identifier(test_run_identifier)
       end
 
-      # @api private
+      # @private
       def waiting_result
         @waiting_result ||= results_repo.find_waiting_result(test_run_id: test_run.id)
       end
 
-      # @api private
+      # @private
       def update_result
         results_repo.pass_waiting_result(waiting_result.id)
       end
 
-      # @api private
+      # @private
       def persist_request
         requests_repo.create(
           request.to_hash.merge(
             test_session_id: test_run.test_session_id,
             result_id: waiting_result.id,
-            name: test.incoming_request_name
+            name: test.config.request_name(test.incoming_request_name)
           )
         )
       end
 
-      # @api private
+      # @private
       def redirect_route
         "/test_sessions/#{test_run.test_session_id}##{waiting_group_id}"
       end
 
-      # @api private
+      # @private
       def test
         @test ||= tests_repo.find(waiting_result.test_id)
       end
 
-      # @api private
+      # @private
       def waiting_group_id
         test.parent.id
       end
 
-      # @api private
+      # @private
       def call(_params)
         if test_run.nil?
           status(500, "Unable to find test run with identifier '#{test_run_identifier}'.")