fix 0.18.2 → 0.19

data/lib/fix/doc.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "error/invalid_specification_name"
+
+module Fix
+  # Module for storing and managing specification documents.
+  #
+  # This module acts as a registry for specification classes and handles
+  # the extraction of test specifications from context objects.
+  #
+  # @api private
+  module Doc
+    # Retrieves the contexts array for a named specification.
+    #
+    # @param name [String, Symbol] The constant name of the specification
+    # @return [Array<Fix::Dsl>] Array of context classes for the specification
+    # @raise [NameError] If specification constant is not found
+    def self.fetch(name)
+      const_get("#{name}::CONTEXTS")
+    end
+
+    # Extracts test specifications from a list of context classes.
+    # Each specification consists of an environment and its associated test data.
+    #
+    # @param contexts [Array<Fix::Dsl>] List of context classes to process
+    # @return [Array<Array>] Array of arrays where each sub-array contains:
+    #   - [0] environment: The test environment instance
+    #   - [1] location: The test file location (as "path:line")
+    #   - [2] requirement: The test requirement (MUST, SHOULD, or MAY)
+    #   - [3] challenges: Array of test challenges to execute
+    def self.extract_specifications(*contexts)
+      contexts.flat_map do |context|
+        extract_context_specifications(context)
+      end
+    end
+
+    # Registers a new specification class under the given name.
+    #
+    # @param name [String, Symbol] Name to register the specification under
+    # @param klass [Class] The specification class to register
+    # @raise [Fix::Error::InvalidSpecificationName] If name is not a valid constant name
+    # @return [void]
+    def self.spec_set(name, klass)
+      const_set(name, klass)
+    rescue ::NameError => _e
+      raise Error::InvalidSpecificationName, name
+    end
+
+    # @private
+    def self.extract_context_specifications(context)
+      env = context.new
+      env.public_methods(false).map do |public_method|
+        [env] + env.public_send(public_method)
+      end
+    end
+
+    private_class_method :extract_context_specifications
+  end
+end

data/lib/fix/dsl.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "defi/method"
+
+require_relative "matcher"
+require_relative "requirement"
+
+module Fix
+  # Abstract class for handling the domain-specific language.
+  #
+  # @api private
+  class Dsl
+    extend Matcher
+    extend Requirement
+
+    # Sets a user-defined property.
+    #
+    # @example
+    #   require "fix"
+    #
+    #   Fix do
+    #     let(:name) { "Bob" }
+    #   end
+    #
+    # @param name [String, Symbol] The name of the property.
+    # @yield The block that defines the property's value
+    # @yieldreturn [Object] The value to be returned by the property
+    #
+    # @return [Symbol] A private method that defines the block content.
+    #
+    # @api public
+    def self.let(name, &)
+      private define_method(name, &)
+    end
+
+    # Defines an example group with user-defined properties that describes a
+    # unit to be tested.
+    #
+    # @example
+    #   require "fix"
+    #
+    #   Fix do
+    #     with password: "secret" do
+    #       it MUST be true
+    #     end
+    #   end
+    #
+    # @param kwargs [Hash] The list of properties to define in this context
+    # @yield The block that defines the specs for this context
+    # @yieldreturn [void]
+    #
+    # @return [Class] A new class representing this context
+    #
+    # @api public
+    def self.with(**kwargs, &)
+      klass = ::Class.new(self)
+      klass.const_get(:CONTEXTS) << klass
+      kwargs.each { |name, value| klass.let(name) { value } }
+      klass.instance_eval(&)
+      klass
+    end
+
+    # Defines an example group that describes a unit to be tested.
+    #
+    # @example
+    #   require "fix"
+    #
+    #   Fix do
+    #     on :+, 2 do
+    #       it MUST be 42
+    #     end
+    #   end
+    #
+    # @param method_name [String, Symbol] The method to send to the subject
+    # @param args [Array] Positional arguments to pass to the method
+    # @param kwargs [Hash] Keyword arguments to pass to the method
+    # @yield The block containing the specifications for this context
+    # @yieldreturn [void]
+    #
+    # @return [Class] A new class representing this context
+    #
+    # @api public
+    def self.on(method_name, *args, **kwargs, &block)
+      klass = ::Class.new(self)
+      klass.const_get(:CONTEXTS) << klass
+
+      const_name = :"MethodContext_#{block.object_id}"
+      const_set(const_name, klass)
+
+      klass.define_singleton_method(:challenges) do
+        challenge = ::Defi::Method.new(method_name, *args, **kwargs)
+        super() + [challenge]
+      end
+
+      klass.instance_eval(&block)
+      klass
+    end
+
+    # Defines a concrete spec definition.
+    #
+    # @example
+    #   require "fix"
+    #
+    #   Fix { it MUST be 42 }
+    #
+    #   Fix do
+    #     it { MUST be 42 }
+    #   end
+    #
+    # @param requirement [Object, nil] The requirement to test
+    # @yield A block defining the requirement if not provided directly
+    # @yieldreturn [Object] The requirement definition
+    #
+    # @return [Symbol] Name of the generated test method
+    #
+    # @raise [ArgumentError] If neither or both requirement and block are provided
+    #
+    # @api public
+    def self.it(requirement = nil, &block)
+      raise ::ArgumentError, "Must provide either requirement or block, not both" if requirement && block
+      raise ::ArgumentError, "Must provide either requirement or block" unless requirement || block
+
+      location = caller_locations(1, 1).fetch(0)
+      location = [location.path, location.lineno].join(":")
+
+      test_method_name = :"test_#{(requirement || block).object_id}"
+      define_method(test_method_name) do
+        [location, requirement || singleton_class.class_eval(&block), self.class.challenges]
+      end
+    end
+
+    # The list of challenges to be addressed to the object to be tested.
+    #
+    # @return [Array<Defi::Method>] A list of challenges.
+    def self.challenges
+      []
+    end
+  end
+end

data/lib/fix/error/invalid_specification_name.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Fix
+  module Error
+    # Error raised when an invalid specification name is provided during declaration
+    class InvalidSpecificationName < ::NameError
+      def initialize(name)
+        super("Invalid specification name '#{name}'. Specification names must be valid Ruby constants.")
+      end
+    end
+  end
+end

data/lib/fix/error/missing_specification_block.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Fix
+  module Error
+    # Error raised when attempting to build a specification without a block
+    class MissingSpecificationBlock < ::ArgumentError
+      MISSING_BLOCK_ERROR = "Block is required for building a specification"
+
+      def initialize
+        super(MISSING_BLOCK_ERROR)
+      end
+    end
+  end
+end

data/lib/fix/error/specification_not_found.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Fix
+  module Error
+    # Error raised when a specification cannot be found at runtime
+    class SpecificationNotFound < ::NameError
+      def initialize(name)
+        super("Specification '#{name}' not found. Make sure it's defined before running the test.")
+      end
+    end
+  end
+end

data/lib/fix/matcher.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "matchi"
+
+module Fix
+  # Collection of expectation matchers.
+  # Provides a comprehensive set of matchers for testing different aspects of objects.
+  #
+  # The following matchers are available:
+  #
+  # Basic Comparison:
+  # - eq(expected)         # Checks equality using eql?
+  #     it MUST eq(42)
+  #     it MUST eq("hello")
+  # - eql(expected)        # Alias for eq
+  # - be(expected)         # Checks exact object identity using equal?
+  #     string = "test"
+  #     it MUST be(string)  # Passes only if it's the same object
+  # - equal(expected)      # Alias for be
+  #
+  # Type Checking:
+  # - be_an_instance_of(class) # Checks exact class match
+  #     it MUST be_an_instance_of(Array)
+  # - be_a_kind_of(class)      # Checks class inheritance and module inclusion
+  #     it MUST be_a_kind_of(Enumerable)
+  #
+  # State & Changes:
+  # - change(object, method)     # Base for checking state changes
+  #   .by(n)                     # Exact change by n
+  #     it MUST change(user, :points).by(5)
+  #   .by_at_least(n)            # Minimum change by n
+  #     it MUST change(counter, :value).by_at_least(10)
+  #   .by_at_most(n)             # Maximum change by n
+  #     it MUST change(account, :balance).by_at_most(100)
+  #   .from(old).to(new)         # Change from old to new value
+  #     it MUST change(user, :status).from("pending").to("active")
+  #   .to(new)                   # Change to new value
+  #     it MUST change(post, :title).to("Updated")
+  #
+  # Value Testing:
+  # - be_within(delta).of(value) # Checks numeric value within delta
+  #     it MUST be_within(0.1).of(3.14)
+  # - match(regex)               # Tests against regular expression
+  #     it MUST match(/^\d{3}-\d{2}-\d{4}$/)  # SSN format
+  # - satisfy { |value| ... }    # Custom matcher with block
+  #     it MUST satisfy { |num| num.even? && num > 0 }
+  #
+  # Exceptions:
+  # - raise_exception(class)     # Checks if code raises exception
+  #     it MUST raise_exception(ArgumentError)
+  #     it MUST raise_exception(CustomError, "specific message")
+  #
+  # State Testing:
+  # - be_true                    # Tests for true
+  #     it MUST be_true          # Only passes for true, not truthy values
+  # - be_false                   # Tests for false
+  #     it MUST be_false         # Only passes for false, not falsey values
+  # - be_nil                     # Tests for nil
+  #     it MUST be_nil
+  #
+  # Predicate Matchers:
+  # - be_*                       # Matches object.*? method
+  #     it MUST be_empty         # Calls empty?
+  #     it MUST be_valid         # Calls valid?
+  #     it MUST be_frozen        # Calls frozen?
+  # - have_*                     # Matches object.has_*? method
+  #     it MUST have_key(:id)    # Calls has_key?
+  #     it MUST have_errors      # Calls has_errors?
+  #
+  # @note All matchers can be used with MUST, MUST_NOT, SHOULD, SHOULD_NOT, and MAY
+  # @see https://github.com/fixrb/matchi for more details about the matchers
+  # @api private
+  module Matcher
+    include Matchi
+  end
+end

data/lib/fix/requirement.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "spectus/requirement/optional"
+require "spectus/requirement/recommended"
+require "spectus/requirement/required"
+
+module Fix
+  # Implements requirement levels as defined in RFC 2119.
+  # Provides methods for specifying different levels of requirements
+  # in test specifications: MUST, SHOULD, and MAY.
+  #
+  # @api private
+  module Requirement
+    # rubocop:disable Naming/MethodName
+
+    # This method means that the definition is an absolute requirement of the
+    # specification.
+    #
+    # @example Test exact equality
+    #   it MUST eq(42)
+    #
+    # @example Test type matching
+    #   it MUST be_an_instance_of(User)
+    #
+    # @example Test state changes
+    #   it MUST change(user, :status).from("pending").to("active")
+    #
+    # @param matcher [#match?] The matcher that defines the required condition
+    # @return [::Spectus::Requirement::Required] An absolute requirement level instance
+    #
+    # @api public
+    def MUST(matcher)
+      ::Spectus::Requirement::Required.new(negate: false, matcher:)
+    end
+
+    # This method means that the definition is an absolute prohibition of the
+    # specification.
+    #
+    # @example Test prohibited state
+    #   it MUST_NOT be_nil
+    #
+    # @example Test prohibited type
+    #   it MUST_NOT be_a_kind_of(AdminUser)
+    #
+    # @example Test prohibited exception
+    #   it MUST_NOT raise_exception(SecurityError)
+    #
+    # @param matcher [#match?] The matcher that defines the prohibited condition
+    # @return [::Spectus::Requirement::Required] An absolute prohibition level instance
+    #
+    # @api public
+    def MUST_NOT(matcher)
+      ::Spectus::Requirement::Required.new(negate: true, matcher:)
+    end
+
+    # This method means that there may exist valid reasons in particular
+    # circumstances to ignore this requirement, but the implications must be
+    # understood and carefully weighed.
+    #
+    # @example Test numeric boundaries
+    #   it SHOULD be_within(0.1).of(expected_value)
+    #
+    # @example Test pattern matching
+    #   it SHOULD match(/^[A-Z][a-z]+$/)
+    #
+    # @example Test custom condition
+    #   it SHOULD satisfy { |obj| obj.valid? && obj.complete? }
+    #
+    # @param matcher [#match?] The matcher that defines the recommended condition
+    # @return [::Spectus::Requirement::Recommended] A recommended requirement level instance
+    #
+    # @api public
+    def SHOULD(matcher)
+      ::Spectus::Requirement::Recommended.new(negate: false, matcher:)
+    end
+
+    # This method means that there may exist valid reasons in particular
+    # circumstances when the behavior is acceptable, but the implications should be
+    # understood and weighed carefully.
+    #
+    # @example Test state changes to avoid
+    #   it SHOULD_NOT change(object, :state)
+    #
+    # @example Test predicate conditions to avoid
+    #   it SHOULD_NOT be_empty
+    #   it SHOULD_NOT have_errors
+    #
+    # @param matcher [#match?] The matcher that defines the discouraged condition
+    # @return [::Spectus::Requirement::Recommended] A discouraged requirement level instance
+    #
+    # @api public
+    def SHOULD_NOT(matcher)
+      ::Spectus::Requirement::Recommended.new(negate: true, matcher:)
+    end
+
+    # This method means that the item is truly optional. Implementations may
+    # include this feature if it enhances their product, and must be prepared to
+    # interoperate with implementations that include or omit this feature.
+    #
+    # @example Test optional functionality
+    #   it MAY respond_to(:cache_key)
+    #
+    # @example Test optional state
+    #   it MAY be_frozen
+    #
+    # @example Test optional predicates
+    #   it MAY have_attachments
+    #
+    # @param matcher [#match?] The matcher that defines the optional condition
+    # @return [::Spectus::Requirement::Optional] An optional requirement level instance
+    #
+    # @api public
+    def MAY(matcher)
+      ::Spectus::Requirement::Optional.new(negate: false, matcher:)
+    end
+
+    # rubocop:enable Naming/MethodName
+  end
+end

data/lib/fix/run.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "expresenter/fail"
+
+module Fix
+  # Executes a test specification by running a subject against a set of challenges
+  # and requirements.
+  #
+  # The Run class orchestrates test execution by:
+  # 1. Evaluating the test subject in the proper environment
+  # 2. Applying a series of method challenges to the result
+  # 3. Verifying the final value against the requirement
+  #
+  # @example Running a simple test
+  #   run = Run.new(env, requirement)
+  #   run.test { MyClass.new }
+  #
+  # @example Running with method challenges
+  #   run = Run.new(env, requirement, challenge1, challenge2)
+  #   run.test { MyClass.new }  # Will call methods defined in challenges
+  #
+  # @api private
+  class Run
+    # The test environment containing defined variables and methods
+    # @return [::Fix::Dsl] A context instance
+    attr_reader :environment
+
+    # The specification requirement to validate against
+    # @return [::Spectus::Requirement::Base] An expectation
+    attr_reader :requirement
+
+    # The list of method calls to apply to the subject
+    # @return [Array<::Defi::Method>] A list of challenges
+    attr_reader :challenges
+
+    # Initializes a new test run with the given environment and challenges.
+    #
+    # @param environment [::Fix::Dsl] Context instance with test setup
+    # @param requirement [::Spectus::Requirement::Base] Expectation to verify
+    # @param challenges [Array<::Defi::Method>] Method calls to apply
+    #
+    # @example
+    #   Run.new(test_env, must_be_positive, increment_method)
+    def initialize(environment, requirement, *challenges)
+      @environment = environment
+      @requirement = requirement
+      @challenges = challenges
+    end
+
+    # Verifies if the subject meets the requirement after applying all challenges.
+    #
+    # @param subject [Proc] The block of code to be tested
+    #
+    # @raise [::Expresenter::Fail] When the test specification fails
+    # @return [::Expresenter::Pass] When the test specification passes
+    #
+    # @example Basic testing
+    #   run.test { 42 }
+    #
+    # @example Testing with subject modification
+    #   run.test { User.new(name: "John") }
+    #
+    # @see https://github.com/fixrb/expresenter
+    def test(&subject)
+      requirement.call { actual_value(&subject) }
+    rescue ::Expresenter::Fail => e
+      e
+    end
+
+    private
+
+    # Computes the final value to test by applying all challenges to the subject.
+    #
+    # @param subject [Proc] The initial test subject
+    # @return [#object_id] The final value after applying all challenges
+    #
+    # @example Internal process
+    #   # If challenges are [:upcase, :reverse]
+    #   # and subject returns "hello"
+    #   # actual_value will return "OLLEH"
+    def actual_value(&subject)
+      initial_value = environment.instance_eval(&subject)
+      challenges.inject(initial_value) do |obj, challenge|
+        challenge.to(obj).call
+      end
+    end
+  end
+end

data/lib/fix/set.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "English"
+
+require_relative "doc"
+require_relative "run"
+
+module Fix
+  # Collection of specifications.
+  #
+  # @api private
+  class Set
+    # @return [Array] A list of specifications.
+    attr_reader :specs
+
+    # Load specifications from a constant name.
+    #
+    # @param name [String, Symbol] The constant name of the specifications.
+    # @return [Set] A new Set instance containing the loaded specifications.
+    #
+    # @api public
+    def self.load(name)
+      new(*Doc.fetch(name))
+    end
+
+    # Initialize a new Set with given contexts.
+    #
+    # @param contexts [Array<::Fix::Dsl>] The list of contexts document.
+    def initialize(*contexts)
+      @specs = Doc.extract_specifications(*contexts).shuffle
+    end
+
+    # Run the test suite against the provided subject.
+    #
+    # @yield The block of code to be tested
+    # @yieldreturn [Object] The result of the code being tested
+    # @return [Boolean] true if all tests pass, exits with false otherwise
+    # @raise [::SystemExit] The test set failed!
+    #
+    # @api public
+    def test(&)
+      suite_passed?(&) || ::Kernel.exit(false)
+    end
+
+    private
+
+    def suite_passed?(&subject)
+      specs.all? { |spec| run_spec(*spec, &subject) }
+    end
+
+    def run_spec(env, location, requirement, challenges, &subject)
+      ::Process.fork { lab(env, location, requirement, challenges, &subject) }
+      ::Process.wait
+      $CHILD_STATUS.success?
+    end
+
+    def lab(env, location, requirement, challenges, &)
+      result = Run.new(env, requirement, *challenges).test(&)
+      report!(location, result)
+      ::Kernel.exit(result.passed?)
+    end
+
+    def report!(path, result)
+      puts "#{path} #{result.colored_string}"
+    end
+  end
+end