fix 0.19 → 0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e44836a2e867dcb513bc3daffa30c6c319e18602be1c4cf0e098d14f7ae4f9b
-  data.tar.gz: 70029c70b7efd078c5d4cafdcdacd1921a2c081e1637f7f2cbc867bfde839781
+  metadata.gz: cb6b67aefa0647614856cce193a81deb17a4310561e48c3d4184b0b1856b0bdc
+  data.tar.gz: a66456067810448477560424cd6f51b23ab9768013f344b598da3a61cc856d2b
 SHA512:
-  metadata.gz: f18450b4cc887e269471c529e95816537f620e342733a3441091b01709feaf44d7f1fe46e7ea2b228f5eca154f410de0e03456f238aa642e2a35ff1d55aa5376
-  data.tar.gz: 3854f42a81ddece26f7e9b7d33d347caf37c885cb65ea1e17910032c279c249aefa6ff73d3b7dccfd205d5824812d72564c79d2b76cc7d0afd2e2c51ad08428e
+  metadata.gz: 7cf39f73a43eaee6b19de405903c8421707f35fd7c3ccf06ff0395c434a3e9f701c596f5ba1ced62fa7edaef80fe17cfbfd6d275ab2716330c3feccfa6a9695c
+  data.tar.gz: 0b23915ab51f8c6d34a013188a07130c6d86eab5e128ddaeae4ef53b3952257ff5e49ef729fae5aaa49064cdb2647d4cd37ddd1fbaed2189170a1ac8834d65c4

data/lib/fix/error/missing_subject_block.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Fix
+  module Error
+    # Error raised when attempting to test a specification without providing a subject block
+    class MissingSubjectBlock < ::ArgumentError
+      MISSING_BLOCK_ERROR = "Subject block is required for testing a specification. " \
+                            "Use: test { subject } or match? { subject }"
+
+      def initialize
+        super(MISSING_BLOCK_ERROR)
+      end
+    end
+  end
+end

data/lib/fix/set.rb

@@ -1,67 +1,210 @@
 # frozen_string_literal: true
 
-require "English"
-
 require_relative "doc"
 require_relative "run"
+require_relative "error/missing_subject_block"
 
 module Fix
-  # Collection of specifications.
+  # Collection of specifications that can be executed as a test suite.
+  #
+  # The Set class is a central component in Fix's architecture that handles:
+  # - Loading and organizing test specifications
+  # - Managing test execution and isolation
+  # - Reporting test results
+  # - Handling process management for test isolation
+  #
+  # It supports both named specifications (loaded via Fix[name]) and anonymous
+  # specifications (created directly via Fix blocks).
+  #
+  # @example Running a simple named specification
+  #   Fix[:Calculator].test { Calculator.new }
+  #
+  # @example Running a complex specification with multiple contexts
+  #   Fix[:UserSystem] do
+  #     with(role: "admin") do
+  #       on :access?, :settings do
+  #         it MUST be_true
+  #       end
+  #     end
+  #
+  #     with(role: "guest") do
+  #       on :access?, :settings do
+  #         it MUST be_false
+  #       end
+  #     end
+  #   end.test { UserSystem.new(role:) }
+  #
+  # @example Using match? for conditional testing
+  #   if Fix[:EmailValidator].match? { email }
+  #     puts "Email is valid"
+  #   end
   #
   # @api private
   class Set
-    # @return [Array] A list of specifications.
-    attr_reader :specs
+    # List of specifications to be tested.
+    # Each specification is an array containing:
+    # - The test environment
+    # - The source location (file:line)
+    # - The requirement (MUST, SHOULD, or MAY)
+    # - The challenges to apply
+    #
+    # @return [Array] List of specifications
+    attr_reader :expected
+
+    class << self
+      # Loads specifications from a registered constant name.
+      #
+      # This method retrieves previously registered specifications and creates
+      # a new Set instance ready for testing. It's typically used in conjunction
+      # with Fix[name] syntax.
+      #
+      # @param name [String, Symbol] The constant name of the specifications
+      # @return [Set] A new Set instance containing the loaded specifications
+      # @raise [Fix::Error::SpecificationNotFound] If specification doesn't exist
+      #
+      # @example Loading a named specification
+      #   Fix::Set.load(:Calculator)
+      #
+      # @example Loading and testing in one go
+      #   Fix::Set.load(:EmailValidator).test { email }
+      #
+      # @api public
+      def load(name)
+        new(*Doc.fetch(name))
+      end
+    end
 
-    # Load specifications from a constant name.
+    # Initialize a new Set with the given contexts.
     #
-    # @param name [String, Symbol] The constant name of the specifications.
-    # @return [Set] A new Set instance containing the loaded specifications.
+    # @param contexts [Array<Fix::Dsl>] List of specification contexts
     #
-    # @api public
-    def self.load(name)
-      new(*Doc.fetch(name))
+    # @example Creating a set with a single context
+    #   Fix::Set.new(calculator_context)
+    #
+    # @example Creating a set with multiple contexts
+    #   Fix::Set.new(base_context, admin_context, guest_context)
+    def initialize(*contexts)
+      @expected = randomize_specs(Doc.extract_specifications(*contexts))
     end
 
-    # Initialize a new Set with given contexts.
+    # Checks if the subject matches all specifications without exiting.
     #
-    # @param contexts [Array<::Fix::Dsl>] The list of contexts document.
-    def initialize(*contexts)
-      @specs = Doc.extract_specifications(*contexts).shuffle
+    # Unlike #test, this method:
+    # - Returns a boolean instead of exiting
+    # - Can be used in conditional logic
+    #
+    # @yield The block of code to be tested
+    # @yieldreturn [Object] The result of the code being tested
+    # @return [Boolean] true if all tests pass, false otherwise
+    #
+    # @example Basic usage
+    #   set.match? { Calculator.new } #=> true
+    #
+    # @example Conditional usage
+    #   if set.match? { user_input }
+    #     save_to_database(user_input)
+    #   end
+    #
+    # @api public
+    def match?(&subject)
+      raise Error::MissingSubjectBlock unless subject
+
+      expected.all? { |spec| run_spec(*spec, &subject) }
     end
 
-    # Run the test suite against the provided subject.
+    # Runs the test suite against the provided subject.
+    #
+    # This method:
+    # - Executes all specifications in random order
+    # - Runs each test in isolation using process forking
+    # - Reports results for each specification
+    # - Exits with failure if any test fails
     #
     # @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!
+    # @return [Boolean] true if all tests pass
+    # @raise [SystemExit] When any test fails (exit code: 1)
+    #
+    # @example Basic usage
+    #   set.test { Calculator.new }
+    #
+    # @example Testing with parameters
+    #   set.test { Game.new(south_variant:, north_variant:) }
+    #
+    # @api public
+    def test(&subject)
+      match?(&subject) || exit_with_failure
+    end
+
+    # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     #
     # @api public
-    def test(&)
-      suite_passed?(&) || ::Kernel.exit(false)
+    def to_s
+      "fix #{expected.inspect}"
     end
 
     private
 
-    def suite_passed?(&subject)
-      specs.all? { |spec| run_spec(*spec, &subject) }
+    # Randomizes the order of specifications for better isolation
+    #
+    # @param specifications [Array] The specifications to randomize
+    # @return [Array] Randomized specifications
+    def randomize_specs(specifications)
+      specifications.shuffle
     end
 
+    # Runs a single specification in a forked process
+    #
+    # @param env [Fix::Dsl] The test environment
+    # @param location [String] The source location of the spec
+    # @param requirement [Object] The test requirement
+    # @param challenges [Array] The test challenges
+    # @yield The subject block to test against
+    # @return [Boolean] true if spec passed
     def run_spec(env, location, requirement, challenges, &subject)
-      ::Process.fork { lab(env, location, requirement, challenges, &subject) }
-      ::Process.wait
-      $CHILD_STATUS.success?
+      child_pid = ::Process.fork { execute_spec(env, location, requirement, challenges, &subject) }
+      _pid, process_status = ::Process.wait2(child_pid)
+      process_status.success?
+    end
+
+    # Executes a specification in its own process
+    #
+    # @param env [Fix::Dsl] The test environment
+    # @param location [String] The source location of the spec
+    # @param requirement [Object] The test requirement
+    # @param challenges [Array] The test challenges
+    # @yield The subject block to test against
+    def execute_spec(env, location, requirement, challenges, &subject)
+      result = Run.new(env, requirement, *challenges).test(&subject)
+      report_result(location, result)
+      exit_with_status(result.passed?)
     end
 
-    def lab(env, location, requirement, challenges, &)
-      result = Run.new(env, requirement, *challenges).test(&)
-      report!(location, result)
-      ::Kernel.exit(result.passed?)
+    # Reports the result of a specification
+    #
+    # @param location [String] The source location of the spec
+    # @param result [Object] The test result
+    def report_result(location, result)
+      puts "#{location} #{result.colored_string}"
     end
 
-    def report!(path, result)
-      puts "#{path} #{result.colored_string}"
+    # Exits the process with a failure status
+    #
+    # @return [void]
+    # @raise [SystemExit] Always
+    def exit_with_failure
+      ::Kernel.exit(false)
+    end
+
+    # Exits the process with the given status
+    #
+    # @param status [Boolean] The exit status
+    # @return [void]
+    # @raise [SystemExit] Always
+    def exit_with_status(status)
+      ::Kernel.exit(status)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fix
 version: !ruby/object:Gem::Version
-  version: '0.19'
+  version: '0.20'
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-01 00:00:00.000000000 Z
+date: 2025-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -70,6 +70,7 @@ files:
 - lib/fix/dsl.rb
 - lib/fix/error/invalid_specification_name.rb
 - lib/fix/error/missing_specification_block.rb
+- lib/fix/error/missing_subject_block.rb
 - lib/fix/error/specification_not_found.rb
 - lib/fix/matcher.rb
 - lib/fix/requirement.rb