spec_forge 0.1.0

data/lib/spec_forge/normalizer/config.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class Config < Normalizer
+      STRUCTURE = {
+        environment: {
+          # Allows for a shorthand:
+          #   environment: rails
+          # Long form:
+          #   environment:
+          #     use: rails
+          type: [String, Hash],
+          default: "rails",
+          structure: {
+            use: {type: String, default: "rails"},
+            preload: {type: String, default: ""},
+            models_path: {
+              type: String,
+              aliases: %i[models],
+              default: ""
+            }
+          }
+        },
+        base_url: {type: String}, # Required
+        authorization: {
+          type: Hash,
+          default: {
+            # Default is a key on this hash
+            default: {}
+          },
+          structure: {
+            default: {
+              type: Hash,
+              structure: {
+                header: {type: String, default: ""},
+                value: {type: String, default: ""}
+              }
+            }
+          }
+        },
+        factories: {
+          type: Hash,
+          default: {},
+          structure: {
+            paths: {
+              type: Array,
+              default: []
+            },
+            auto_discover: {
+              type: [TrueClass, FalseClass],
+              default: true
+            }
+          }
+        }
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty config hash
+      #
+      # @return [Hash]
+      #
+      def default_config
+        Config.default
+      end
+
+      #
+      # Normalizes a config hash by standardizing its keys while ensuring the required data
+      # is provided or defaulted.
+      # Raises InvalidStructureError if anything is missing/invalid type
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash as a new instance
+      #
+      def normalize_config!(input)
+        raise_errors! do
+          normalize_config(input)
+        end
+      end
+
+      #
+      # Normalize a config hash
+      # Used internally by .normalize_config, but is available for utility
+      #
+      # @param config [Hash] Config representation as a Hash
+      #
+      # @return [Array] Two item array
+      #   First - The normalized hash
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_config(config)
+        raise InvalidTypeError.new(config, Hash, for: "config") unless Type.hash?(config)
+
+        Normalizer::Config.new("config", config).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/constraint.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class Constraint < Normalizer
+      STRUCTURE = {
+        status: {
+          type: Integer
+        },
+        json: {
+          type: Hash,
+          default: {}
+        }
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty constraint hash
+      #
+      # @return [Hash]
+      #
+      def default_constraint
+        Constraint.default
+      end
+
+      #
+      # Normalize a constraint hash
+      # Used internally by .normalize_spec, but is available for utility
+      #
+      # @param constraint [Hash] Constraint representation as a Hash
+      #
+      # @return [Array] Two item array
+      #   First - The normalized hash
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_constraint(constraint)
+        raise InvalidTypeError.new(constraint, Hash, for: "expect") unless Type.hash?(constraint)
+
+        Normalizer::Constraint.new("expect", constraint).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/expectation.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class Expectation < Normalizer
+      STRUCTURE = {
+        name: {type: String, default: ""},
+        base_url: Normalizer::SHARED_ATTRIBUTES[:base_url],
+        url: Normalizer::SHARED_ATTRIBUTES[:url],
+        http_method: Normalizer::SHARED_ATTRIBUTES[:http_method],
+        headers: Normalizer::SHARED_ATTRIBUTES[:headers],
+        query: Normalizer::SHARED_ATTRIBUTES[:query],
+        body: Normalizer::SHARED_ATTRIBUTES[:body],
+        variables: Normalizer::SHARED_ATTRIBUTES[:variables],
+        expect: {type: Hash}
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty expectation hash
+      #
+      # @return [Hash]
+      #
+      def default_expectation
+        Expectation.default
+      end
+
+      #
+      # Normalize an array of expectation hashes
+      #
+      # @raises InvalidStructureError if anything is missing/invalid type
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash as a new instance
+      #
+      def normalize_expectations!(input)
+        raise_errors! do
+          normalize_expectations(input)
+        end
+      end
+
+      #
+      # Normalize an array of expectation hashes
+      # Used internally by .normalize_spec, but is available for utility
+      #
+      # @param expectations [Array<Hash>] An array of expectation hashes
+      #
+      # @return [Array] Two item array
+      #   First - The normalized Array<Hash>
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_expectations(expectations)
+        if !Type.array?(expectations)
+          raise InvalidTypeError.new(expectations, Array, for: "\"expectations\" on spec")
+        end
+
+        final_errors = Set.new
+        final_output = expectations.map.with_index do |expectation, index|
+          normalizer = Normalizer::Expectation.new("expectation (item #{index})", expectation)
+          output, errors = normalizer.normalize
+
+          # If expect is not provided, skip the constraints
+          if (constraint = expectation[:expect])
+            constraint_output, constraint_errors = Normalizer::Constraint.new(
+              "expect (item #{index})", constraint
+            ).normalize
+
+            output[:expect] = constraint_output
+            errors.merge(constraint_errors) if constraint_errors.size > 0
+          end
+
+          final_errors.merge(errors) if errors.size > 0
+          output
+        end
+
+        [final_output, final_errors]
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/factory.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class Factory < Normalizer
+      STRUCTURE = {
+        model_class: {
+          type: String,
+          aliases: %i[class],
+          default: ""
+        },
+        variables: Normalizer::SHARED_ATTRIBUTES[:variables],
+        attributes: {
+          type: Hash,
+          default: {}
+        }
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty factory hash
+      #
+      # @return [Hash]
+      #
+      def default_factory
+        Factory.default
+      end
+
+      #
+      # Normalizes a factory hash by standardizing its keys while ensuring the required data
+      # is provided or defaulted.
+      # Raises InvalidStructureError if anything is missing/invalid type
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash as a new instance
+      #
+      def normalize_factory!(input)
+        raise_errors! do
+          normalize_factory(input)
+        end
+      end
+
+      #
+      # Normalize a factory hash
+      # Used internally by .normalize_factory, but is available for utility
+      #
+      # @param factory [Hash] Factory representation as a Hash
+      #
+      # @return [Array] Two item array
+      #   First - The normalized hash
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_factory(factory)
+        raise InvalidTypeError.new(factory, Hash, for: "factory") unless Type.hash?(factory)
+
+        Normalizer::Factory.new("factory", factory).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/factory_reference.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class FactoryReference < Normalizer
+      STRUCTURE = {
+        attributes: {
+          type: Hash,
+          default: {}
+        },
+        build_strategy: {
+          type: String,
+          aliases: %i[strategy],
+          default: "create"
+        }
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty Attribute::Factory hash
+      #
+      # @return [Hash]
+      #
+      def default_factory_reference
+        FactoryReference.default
+      end
+
+      #
+      # Normalizes a Attribute::Factory hash by standardizing
+      # its keys while ensuring the required data is provided or defaulted.
+      # Raises InvalidStructureError if anything is missing/invalid type
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash as a new instance
+      #
+      def normalize_factory_reference!(input, **)
+        raise_errors! do
+          normalize_factory_reference(input, **)
+        end
+      end
+
+      #
+      # Normalize a factory hash
+      # Used internally by .normalize_factory_reference, but is available for utility
+      #
+      # @param factory [Hash] Attribute::Factory representation as a Hash
+      #
+      # @return [Array] Two item array
+      #   First - The normalized hash
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_factory_reference(factory, label: "factory reference")
+        if !Type.hash?(factory)
+          raise InvalidTypeError.new(factory, Hash, for: "factory reference")
+        end
+
+        Normalizer::FactoryReference.new(label, factory).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/spec.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class Spec < Normalizer
+      STRUCTURE = {
+        base_url: Normalizer::SHARED_ATTRIBUTES[:base_url],
+        url: Normalizer::SHARED_ATTRIBUTES[:url],
+        http_method: Normalizer::SHARED_ATTRIBUTES[:http_method],
+        headers: Normalizer::SHARED_ATTRIBUTES[:headers],
+        query: Normalizer::SHARED_ATTRIBUTES[:query],
+        body: Normalizer::SHARED_ATTRIBUTES[:body],
+        variables: Normalizer::SHARED_ATTRIBUTES[:variables],
+        expectations: {type: Array}
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty spec hash
+      #
+      # @return [Hash]
+      #
+      def default_spec
+        Spec.default
+      end
+
+      #
+      # Normalizes a complete spec hash by standardizing its keys while ensuring the required data
+      # is provided or defaulted.
+      # Raises InvalidStructureError if anything is missing/invalid type
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash as a new instance
+      #
+      def normalize_spec!(input)
+        raise_errors! do
+          output, errors = normalize_spec(input)
+
+          # Process expectations
+          if (expectations = input[:expectations]) && Type.array?(expectations)
+            expectation_output, expectation_errors = normalize_expectations(expectations)
+
+            output[:expectations] = expectation_output
+            errors += expectation_errors if expectation_errors.size > 0
+          end
+
+          [output, errors]
+        end
+      end
+
+      #
+      # Normalize a spec hash
+      # Used internally by .normalize_spec, but is available for utility
+      #
+      # @param spec [Hash] Spec representation as a Hash
+      #
+      # @return [Array] Two item array
+      #   First - The normalized hash
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_spec(spec)
+        raise InvalidTypeError.new(spec, Hash, for: "spec") unless Type.hash?(spec)
+
+        Normalizer::Spec.new("spec", spec).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    SHARED_ATTRIBUTES = {
+      base_url: {
+        type: String,
+        default: ""
+      },
+      url: {
+        type: String,
+        aliases: %i[path],
+        default: ""
+      },
+      http_method: {
+        type: String,
+        aliases: %i[method],
+        default: ""
+      },
+      headers: {
+        type: Hash,
+        default: {}
+      },
+      query: {
+        type: Hash,
+        aliases: %i[params],
+        default: {}
+      },
+      body: {
+        type: Hash,
+        aliases: %i[data],
+        default: {}
+      },
+      variables: {
+        type: Hash,
+        default: {}
+      }
+    }.freeze
+
+    STRUCTURE = {}
+
+    class << self
+      #
+      # Raises any errors collected by the block
+      #
+      # @raises InvalidStructureError
+      #
+      # @private
+      #
+      def raise_errors!(&block)
+        errors = Set.new
+
+        begin
+          output, new_errors = yield
+          errors.merge(new_errors) if new_errors.size > 0
+        rescue => e
+          errors << e
+        end
+
+        raise InvalidStructureError.new(errors) if errors.size > 0
+
+        output
+      end
+
+      #
+      # Returns a default version of this normalizer
+      #
+      # @private
+      #
+      def default
+        new("", "").default
+      end
+    end
+
+    attr_reader :label, :input, :structure
+
+    #
+    # Creates a normalizer for normalizing Hash data based on a structure
+    #
+    # @param label [String] A label that describes the data itself
+    # @param input [Hash] The data to normalize
+    # @param structure [Hash] The structure to normalize the data to
+    #
+    def initialize(label, input, structure: self.class::STRUCTURE)
+      @label = label
+      @input = input
+      @structure = structure
+    end
+
+    #
+    # Normalizes the data and returns the result
+    #
+    # @return [Hash] The normalized data
+    #
+    def normalize
+      normalize_to_structure
+    end
+
+    #
+    # Returns a hash with the default structure
+    #
+    # @return [Hash]
+    #
+    def default
+      structure.transform_values do |value|
+        if (default = value[:default])
+          default.dup
+        elsif value[:type] == Integer # Can't call new on int
+          0
+        else
+          value[:type].new
+        end
+      end
+    end
+
+    protected
+
+    def normalize_to_structure
+      output, errors = {}, Set.new
+
+      structure.each do |key, attribute|
+        type_class = attribute[:type]
+        aliases = attribute[:aliases] || []
+        sub_structure = attribute[:structure]
+        default = attribute[:default]
+        required = !attribute.key?(:default)
+
+        # Get the value
+        value = value_from_keys(input, [key] + aliases)
+
+        # Default the value if needed
+        value = default.dup if !required && value.nil?
+
+        # Type + existence check
+        if !valid_class?(value, type_class)
+          raise InvalidTypeError.new(value, type_class, for: "\"#{key}\" on #{label}")
+        end
+
+        value =
+          case [value.class, sub_structure.class]
+          when [Hash, Hash]
+            new_value, new_errors = self.class
+              .new(label, value, structure: sub_structure)
+              .normalize
+
+            errors += new_errors if new_errors.size > 0
+            new_value
+          else
+            value
+          end
+
+        # Store
+        output[key] = value
+      rescue => e
+        errors << e
+      end
+
+      [output, errors]
+    end
+
+    def value_from_keys(hash, keys)
+      hash.find { |k, v| keys.include?(k) }&.second
+    end
+
+    def valid_class?(value, expected_type)
+      if expected_type.instance_of?(Array)
+        expected_type.any? { |type| value.is_a?(type) }
+      else
+        value.is_a?(expected_type)
+      end
+    end
+  end
+end
+
+#######################################################################
+# These need to be required after the base class due to them requiring
+# a constant
+require_relative "normalizer/config"
+require_relative "normalizer/constraint"
+require_relative "normalizer/expectation"
+require_relative "normalizer/factory_reference"
+require_relative "normalizer/factory"
+require_relative "normalizer/spec"

data/lib/spec_forge/runner.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Creates a spec runner and defines the spec with RSpec
+    #
+    # @param spec [Spec] The spec to run
+    #
+    def initialize(spec)
+      define_spec(spec)
+    end
+
+    #
+    # Runs any RSpec specs
+    #
+    def run
+      RSpec::Core::Runner.disable_autorun!
+      RSpec::Core::Runner.run([], $stderr, $stdout)
+    end
+
+    #
+    # Defines a spec with RSpec
+    #
+    # @param spec_forge [Spec] The spec to define
+    #
+    def define_spec(spec_forge)
+      runner_forge = self
+
+      RSpec.describe(spec_forge.name) do
+        spec_forge.expectations.each do |expectation_forge|
+          describe(expectation_forge.name) do
+            runner_forge.define_variables(self, expectation_forge)
+            runner_forge.define_examples(self, expectation_forge)
+          end
+        end
+      end
+    end
+
+    #
+    # Defines any variables as let statements in RSpec
+    #
+    # @param context [RSpec::ExampleGroup] The rspec example group for this spec
+    # @param expectation [Expectation] The expectation that holds the variables
+    #
+    def define_variables(context, expectation)
+      expectation.variables.each do |variable_name, attribute|
+        context.let(variable_name, &attribute.to_proc)
+      end
+    end
+
+    #
+    # Defines the expectation itself using the constraint
+    #
+    # @param context [RSpec::ExampleGroup] The RSpec example group for this spec
+    # @param expectation [Expectation] The expectation that holds the constraint
+    #
+    def define_examples(context, expectation)
+      context.instance_exec(expectation) do |expectation|
+        # Ensures the only one API call occurs per expectation
+        before(:all) { @response = expectation.http_client.call }
+
+        constraints = expectation.constraints.resolve
+        request = expectation.http_client.request
+
+        # Define the example group
+        context "#{request.http_method} #{request.url}" do
+          subject(:response) { @response }
+
+          # Status check
+          expected_status = constraints[:status]
+          it "expects the response to return a status code of #{expected_status}" do
+            expect(response.status).to eq(expected_status)
+          end
+
+          # JSON check
+          expected_json = constraints[:json]
+          if expected_json.size > 0
+            it "expects the body to return valid JSON" do
+              expect(response.body).to be_kind_of(Hash)
+            end
+
+            it "expects the body to include values" do
+              expect(response.body).to include(expected_json)
+            end
+          end
+        end
+      end
+    end
+  end
+end