fix 1.0.0.beta10 → 1.0.0.beta12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af0a01072f39d7c105aff0bde77c97ce31c9aae8a1144e29a00b9098017cb436
-  data.tar.gz: cab7ff1e39fc58599b712ff53597534535e86bf1422f0f10c926e14d1e267e3f
+  metadata.gz: 4d32cb2da3e2823f71175074536af7f55c981cba88f1fc39952f5c91ecc27756
+  data.tar.gz: bfbf3da66b20085030ecffadbfe908dfe90ea3fe5620fdfaceeedbb5eaec0e9e
 SHA512:
-  metadata.gz: 90f831b90a8faaabf56db03f17d03905e6c41eb18e0f1873db78e0de30540e46b4b395c7fb19f80b3ccbc6b3e560978c42fb0ff8066b6b912151f2785249b51b
-  data.tar.gz: 4b1f58e67584042977f803b53119d090e76f9848b6b470a86aeefaa5f5a195afe11f3ab98d3383e1c5e1e819ff570b890bff58aa734d2c19c6e3079d75a95ffd
+  metadata.gz: 1e66633ce3e37380f20f83f3747ef158e9baadc0853898850972c7e119fe7615eadd53c3197c9bfbd8e48f341d38991060f8dfba16070f34953a08208eefa5bf
+  data.tar.gz: 798abf5941f2fbac379d6b19622d1dfe8fd278c81a715a8e1f55a0f8c91aa6b0b1febfd2a60241ddb9a12f5320ed112a77a0a39f860d3e26e43985277f4d0e99

data/README.md

@@ -1,27 +1,20 @@
-# Fix
+# Fix Framework
 
 [![Home](https://img.shields.io/badge/Home-fixrb.dev-00af8b)](https://fixrb.dev/)
 [![Version](https://img.shields.io/github/v/tag/fixrb/fix?label=Version&logo=github)](https://github.com/fixrb/fix/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/fix/main)
-[![Ruby](https://github.com/fixrb/fix/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/fix/actions?query=workflow%3Aruby+branch%3Amain)
-[![RuboCop](https://github.com/fixrb/fix/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/fix/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/fixrb/fix?label=License&logo=github)](https://github.com/fixrb/fix/raw/main/LICENSE.md)
 
-![Fix specing framework for Ruby](https://fixrb.dev/fix.webp "Fix")
+## Introduction
 
-## Project Goals
-
-- **Distinguish Specifications from Examples**: Clear separation between what is expected (specifications) and how it's demonstrated (examples).
-- **Logic-Free Specification Documents**: Create specifications that are straightforward and free of complex logic, focusing purely on defining expected behaviors.
-- **Nuanced Semantic Language in Specifications**: Utilize a rich, nuanced semantic language, similar to that in RFC 2119, employing keywords like MUST, SHOULD, and MAY to define different levels of requirement in specifications.
-- **Fast and Individual Test Execution**: Enable quick execution of tests on an individual basis, providing immediate feedback on compliance with specifications.
+Fix is a modern Ruby testing framework that emphasizes clear separation between specifications and examples. Unlike traditional testing frameworks, Fix focuses on creating pure specification documents that define expected behaviors without mixing in implementation details.
 
 ## Installation
 
 Add to your Gemfile:
 
 ```ruby
-gem "fix", ">= 1.0.0.beta10"
+gem "fix", ">= 1.0.0.beta12"
 ```
 
 Then execute:
@@ -36,15 +29,161 @@ Or install it yourself:
 gem install fix --pre
 ```
 
-## Example
+## Core Principles
+
+- **Specifications vs Examples**: Fix makes a clear distinction between specifications (what is expected) and examples (how it's demonstrated). This separation leads to cleaner, more maintainable test suites.
+
+- **Logic-Free Specifications**: Your specification documents remain pure and focused on defining behaviors, without getting cluttered by implementation logic.
+
+- **Rich Semantic Language**: Following RFC 2119 conventions, Fix uses precise language with keywords like MUST, SHOULD, and MAY to clearly define different requirement levels in specifications.
+
+- **Fast Individual Testing**: Tests execute quickly and independently, providing rapid feedback on specification compliance.
+
+## Framework Features
+
+### Property Definition with `let`
+
+Define reusable properties across your specifications:
+
+```ruby
+Fix do
+  let(:name) { "Bob" }
+  let(:age) { 42 }
+
+  it MUST eq name
+end
+```
+
+### Context Creation with `with`
+
+Test behavior under different conditions:
+
+```ruby
+Fix do
+  with name: "Alice", role: "admin" do
+    it MUST be_allowed
+  end
+
+  with name: "Bob", role: "guest" do
+    it MUST_NOT be_allowed
+  end
+end
+```
+
+### Method Testing with `on`
+
+Test how objects respond to specific messages:
+
+```ruby
+Fix do
+  on :upcase do
+    it MUST eq "HELLO"
+  end
+
+  on :+, 2 do
+    it MUST eq 42
+  end
+end
+```
+
+### Requirement Levels
+
+Fix provides three levels of requirements, each with clear semantic meaning:
 
-Specifications for a `Duck` class:
+- **MUST/MUST_NOT**: Absolute requirements or prohibitions
+- **SHOULD/SHOULD_NOT**: Recommended practices with valid exceptions
+- **MAY**: Optional features
 
 ```ruby
-# examples/duck/fix.rb
+Fix do
+  it MUST be_valid           # Required
+  it SHOULD be_optimized     # Recommended
+  it MAY include_metadata    # Optional
+end
+```
+
+## Quick Start
 
+Create your first test file:
+
+```ruby
+# first_test.rb
 require "fix"
 
+Fix :HelloWorld do
+  it MUST eq "Hello, World!"
+end
+
+Fix[:HelloWorld].test { "Hello, World!" }
+```
+
+Run it:
+
+```sh
+ruby first_test.rb
+```
+
+## Real-World Examples
+
+Fix is designed to work with real-world applications of any complexity. Here are some examples demonstrating how Fix can be used in different scenarios:
+
+### Example 1: User Account Management
+
+Here's a comprehensive example showing how to specify a user account system:
+
+```ruby
+Fix :UserAccount do
+  # Define reusable properties
+  let(:admin) { User.new(role: "admin") }
+  let(:guest) { User.new(role: "guest") }
+
+  # Test basic instance properties
+  it MUST be_an_instance_of User
+
+  # Test with different contexts
+  with role: "admin" do
+    it MUST be_admin
+
+    on :can_access?, "settings" do
+      it MUST be_true
+    end
+  end
+
+  with role: "guest" do
+    it MUST_NOT be_admin
+
+    on :can_access?, "settings" do
+      it MUST be_false
+    end
+  end
+
+  # Test specific methods
+  on :full_name do
+    with first_name: "John", last_name: "Doe" do
+      it MUST eq "John Doe"
+    end
+  end
+
+  on :update_password, "new_password" do
+    it MUST change(admin, :password_hash)
+    it MUST be_true  # Return value check
+  end
+end
+```
+
+This example demonstrates:
+- Using `let` to define test fixtures
+- Context-specific testing with `with`
+- Method behavior testing with `on`
+- Different requirement levels with `MUST`/`MUST_NOT`
+- Testing state changes with the `change` matcher
+- Nested contexts for complex scenarios
+
+### Example 2: Duck Specification
+
+Here's how Fix can be used to specify a Duck class:
+
+```ruby
 Fix :Duck do
   it SHOULD be_an_instance_of :Duck
 
@@ -63,11 +202,9 @@ Fix :Duck do
 end
 ```
 
-Implementing the `Duck` class:
+The implementation:
 
 ```ruby
-# examples/duck/app.rb
-
 class Duck
   def walks
     "Klop klop!"
@@ -86,36 +223,92 @@ end
 Running the test:
 
 ```ruby
-# examples/duck/test.rb
-
-require_relative "app"
-require_relative "fix"
-
 Fix[:Duck].test { Duck.new }
 ```
 
-Execute:
+## Available Matchers
 
-```sh
-ruby examples/duck/test.rb
-```
+Fix includes a comprehensive set of matchers through its integration with the [Matchi library](https://github.com/fixrb/matchi):
+
+### Basic Comparison Matchers
+- `eq(expected)` - Tests equality using `eql?`
+- `be(expected)` - Tests object identity using `equal?`
+
+### Type Checking Matchers
+- `be_an_instance_of(class)` - Verifies exact class match
+- `be_a_kind_of(class)` - Checks class inheritance and module inclusion
+
+### Change Testing Matchers
+- `change(object, method)` - Base matcher for state changes
+  - `.by(n)` - Expects exact change by n
+  - `.by_at_least(n)` - Expects minimum change by n
+  - `.by_at_most(n)` - Expects maximum change by n
+  - `.from(old).to(new)` - Expects change from old to new value
+  - `.to(new)` - Expects change to new value
+
+### Numeric Matchers
+- `be_within(delta).of(value)` - Tests if a value is within ±delta of expected value
 
-Expected output:
+### Pattern Matchers
+- `match(regex)` - Tests string against regular expression pattern
+- `satisfy { |value| ... }` - Custom matching with block
+
+### State Matchers
+- `be_true` - Tests for true
+- `be_false` - Tests for false
+- `be_nil` - Tests for nil
+
+### Exception Matchers
+- `raise_exception(class)` - Tests if code raises specified exception
+
+### Dynamic Predicate Matchers
+- `be_*` - Dynamically matches `object.*?` methods (e.g., `be_empty` calls `empty?`)
+- `have_*` - Dynamically matches `object.has_*?` methods (e.g., `have_key` calls `has_key?`)
+
+Example usage:
+
+```ruby
+Fix :Calculator do
+  it MUST be_an_instance_of Calculator
 
-```txt
-(irb):3 Success: expected #<Duck:0x00007fb2fa208708> to be an instance of Duck.
-(irb):7 Success: expected to eq "Swoosh...".
-(irb):15 NoMethodError: undefined method `sings' for #<Duck:0x00007fb2fd8371d0>.
-(irb):6 Success: expected "Swoosh..." to be an instance of String.
-(irb):11 Success: undefined method `speaks' for #<Duck:0x00007fb2fcc79258>.
+  on :add, 2, 3 do
+    it MUST eq 5
+    it MUST be_within(0.001).of(5.0)
+  end
+
+  on :divide, 1, 0 do
+    it MUST raise_exception ZeroDivisionError
+  end
+
+  with numbers: [1, 2, 3] do
+    it MUST_NOT be_empty
+    it MUST satisfy { |result| result.all? { |n| n.positive? } }
+  end
+end
 ```
 
-## Contact
+## Why Choose Fix?
+
+Fix brings several unique advantages to Ruby testing that set it apart from traditional testing frameworks:
+
+- **Clear Separation of Concerns**: Keep your specifications clean and your examples separate
+- **Semantic Precision**: Express requirements with different levels of necessity
+- **Fast Execution**: Get quick feedback on specification compliance
+- **Pure Specifications**: Write specification documents that focus on behavior, not implementation
+- **Rich Matcher Library**: Comprehensive set of matchers for different testing needs
+- **Modern Ruby**: Takes advantage of modern Ruby features and practices
+
+## Get Started
+
+Ready to write better specifications? Visit our [GitHub repository](https://github.com/fixrb/fix) to start using Fix in your Ruby projects.
+
+## Community & Resources
 
-- [Home page](https://fixrb.dev/)
-- [Source code](https://github.com/fixrb/fix)
-- [API Documentation](https://rubydoc.info/gems/fix)
-- [Twitter](https://twitter.com/fix_rb)
+- [Blog](https://fixrb.dev/) - Related articles
+- [Bluesky](https://bsky.app/profile/fixrb.dev) - Latest updates and discussions
+- [Documentation](https://www.rubydoc.info/gems/fix) - Comprehensive guides and API reference
+- [Source Code](https://github.com/fixrb/fix) - Contribute and report issues
+- [asciinema](https://asciinema.org/~fix) - Watch practical examples in action
 
 ## Versioning
 
@@ -125,11 +318,6 @@ __Fix__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 The [gem](https://rubygems.org/gems/fix) is available as open source under the terms of the [MIT License](https://github.com/fixrb/fix/raw/main/LICENSE.md).
 
----
+## Sponsors
 
-<p>
-  This project is sponsored by:<br />
-  <a href="https://sashite.com/"><img
-    src="https://github.com/fixrb/fix/raw/main/img/sashite.png"
-    alt="Sashité" /></a>
-</p>
+This project is sponsored by [Sashité](https://sashite.com/)

data/lib/fix/dsl.rb

@@ -95,13 +95,20 @@ module Fix
     #
     #   Fix { it MUST be 42 }
     #
+    #   Fix do
+    #     it { MUST be 42 }
+    #   end
+    #
     # @api public
-    def self.it(requirement)
+    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(":")
 
-      define_method(:"test_#{requirement.object_id}") do
-        [location, requirement, self.class.challenges]
+      define_method(:"test_#{(requirement || block).object_id}") do
+        [location, requirement || singleton_class.class_eval(&block), self.class.challenges]
       end
     end
 

data/lib/fix/matcher.rb

@@ -5,237 +5,45 @@ require "matchi"
 module Fix
   # Collection of expectation matchers.
   #
+  # The following matchers are available:
+  #
+  # Basic Comparison:
+  # - eq(expected)         # Checks equality using eql?
+  # - eql(expected)        # Alias for eq
+  # - be(expected)         # Checks exact object identity using equal?
+  # - equal(expected)      # Alias for be
+  #
+  # Type Checking:
+  # - be_an_instance_of(class) # Checks exact class match
+  # - be_a_kind_of(class)      # Checks class inheritance and module inclusion
+  #
+  # State & Changes:
+  # - change(object, method)     # Base for checking state changes
+  #   .by(n)                     # Exact change by n
+  #   .by_at_least(n)            # Minimum change by n
+  #   .by_at_most(n)             # Maximum change by n
+  #   .from(old).to(new)         # Change from old to new value
+  #   .to(new)                   # Change to new value
+  #
+  # Value Testing:
+  # - be_within(delta).of(value) # Checks numeric value within delta
+  # - match(regex)               # Tests against regular expression
+  # - satisfy { |value| ... }    # Custom matcher with block
+  #
+  # Exceptions:
+  # - raise_exception(class)     # Checks if code raises exception
+  #
+  # State Testing:
+  # - be_true                    # Tests for true
+  # - be_false                   # Tests for false
+  # - be_nil                     # Tests for nil
+  #
+  # Predicate Matchers:
+  # - be_*                       # Matches object.*? method
+  # - have_*                     # Matches object.has_*? method
+  #
   # @api private
   module Matcher
-    # Equivalence matcher
-    #
-    # @example
-    #   matcher = eq("foo")
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
-    #
-    # @param expected [#eql?] An expected equivalent object.
-    #
-    # @return [#matches?] An equivalence matcher.
-    #
-    # @api public
-    def eq(expected)
-      ::Matchi::Eq.new(expected)
-    end
-
-    alias eql eq
-
-    # Identity matcher
-    #
-    # @example
-    #   object = "foo"
-    #   matcher = be(object)
-    #   matcher.matches? { object } # => true
-    #   matcher.matches? { "foo" } # => false
-    #
-    # @param expected [#equal?] The expected identical object.
-    #
-    # @return [#matches?] An identity matcher.
-    #
-    # @api public
-    def be(expected)
-      ::Matchi::Be.new(expected)
-    end
-
-    alias equal be
-
-    # Comparisons matcher
-    #
-    # @example
-    #   matcher = be_within(1).of(41)
-    #   matcher.matches? { 42 } # => true
-    #   matcher.matches? { 43 } # => false
-    #
-    # @param delta [Numeric] A numeric value.
-    #
-    # @return [#matches?] A comparison matcher.
-    #
-    # @api public
-    def be_within(delta)
-      ::Matchi::BeWithin.new(delta)
-    end
-
-    # Regular expressions matcher
-    #
-    # @example
-    #   matcher = match(/^foo$/)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
-    #
-    # @param expected [#match] A regular expression.
-    #
-    # @return [#matches?] A regular expression matcher.
-    #
-    # @api public
-    def match(expected)
-      ::Matchi::Match.new(expected)
-    end
-
-    # Expecting errors matcher
-    #
-    # @example
-    #   matcher = raise_exception(NameError)
-    #   matcher.matches? { Boom } # => true
-    #   matcher.matches? { true } # => false
-    #
-    # @param expected [Exception, #to_s] The expected exception name.
-    #
-    # @return [#matches?] An error matcher.
-    #
-    # @api public
-    def raise_exception(expected)
-      ::Matchi::RaiseException.new(expected)
-    end
-
-    # True matcher
-    #
-    # @example
-    #   matcher = be_true
-    #   matcher.matches? { true } # => true
-    #   matcher.matches? { false } # => false
-    #   matcher.matches? { nil } # => false
-    #   matcher.matches? { 4 } # => false
-    #
-    # @return [#matches?] A `true` matcher.
-    #
-    # @api public
-    def be_true
-      be(true)
-    end
-
-    # False matcher
-    #
-    # @example
-    #   matcher = be_false
-    #   matcher.matches? { false } # => true
-    #   matcher.matches? { true } # => false
-    #   matcher.matches? { nil } # => false
-    #   matcher.matches? { 4 } # => false
-    #
-    # @return [#matches?] A `false` matcher.
-    #
-    # @api public
-    def be_false
-      be(false)
-    end
-
-    # Nil matcher
-    #
-    # @example
-    #   matcher = be_nil
-    #   matcher.matches? { nil } # => true
-    #   matcher.matches? { false } # => false
-    #   matcher.matches? { true } # => false
-    #   matcher.matches? { 4 } # => false
-    #
-    # @return [#matches?] A `nil` matcher.
-    #
-    # @api public
-    def be_nil
-      be(nil)
-    end
-
-    # Type/class matcher
-    #
-    # @example
-    #   matcher = be_an_instance_of(String)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { 4 } # => false
-    #
-    # @param expected [Class, #to_s] The expected class name.
-    #
-    # @return [#matches?] A type/class matcher.
-    #
-    # @api public
-    def be_an_instance_of(expected)
-      ::Matchi::BeAnInstanceOf.new(expected)
-    end
-
-    # Change matcher
-    #
-    # @example
-    #   object = []
-    #   matcher = change(object, :length).by(1)
-    #   matcher.matches? { object << 1 } # => true
-    #
-    #   object = []
-    #   matcher = change(object, :length).by_at_least(1)
-    #   matcher.matches? { object << 1 } # => true
-    #
-    #   object = []
-    #   matcher = change(object, :length).by_at_most(1)
-    #   matcher.matches? { object << 1 } # => true
-    #
-    #   object = "foo"
-    #   matcher = change(object, :to_s).from("foo").to("FOO")
-    #   matcher.matches? { object.upcase! } # => true
-    #
-    #   object = "foo"
-    #   matcher = change(object, :to_s).to("FOO")
-    #   matcher.matches? { object.upcase! } # => true
-    #
-    # @param object [#object_id]  An object.
-    # @param method [Symbol]      The name of a method.
-    #
-    # @return [#matches?] A change matcher.
-    #
-    # @api public
-    def change(object, method, ...)
-      ::Matchi::Change.new(object, method, ...)
-    end
-
-    # Satisfy matcher
-    #
-    # @example
-    #   matcher = satisfy { |value| value == 42 }
-    #   matcher.matches? { 42 } # => true
-    #
-    # @yield [value] A block that defines the satisfaction criteria
-    # @yieldparam value The value to test
-    # @yieldreturn [Boolean] true if the value satisfies the criteria
-    #
-    # @return [#matches?] A satisfy matcher.
-    #
-    # @api public
-    def satisfy(&)
-      ::Matchi::Satisfy.new(&)
-    end
-
-    private
-
-    # Predicate matcher, or default method missing behavior.
-    #
-    # @example Empty predicate matcher
-    #   matcher = be_empty
-    #   matcher.matches? { [] } # => true
-    #   matcher.matches? { [4] } # => false
-    def method_missing(name, ...)
-      return super unless predicate_matcher_name?(name)
-
-      ::Matchi::Predicate.new(name, ...)
-    end
-
-    # :nocov:
-
-    # Hook method to return whether the obj can respond to id method or not.
-    def respond_to_missing?(name, include_private = false)
-      predicate_matcher_name?(name) || super
-    end
-
-    # :nocov:
-
-    # Predicate matcher name detector.
-    #
-    # @param name [Array, Symbol] The name of a potential predicate matcher.
-    #
-    # @return [Boolean] Indicates if it is a predicate matcher name or not.
-    def predicate_matcher_name?(name)
-      name.start_with?("be_", "have_") && !name.end_with?("!", "?")
-    end
+    include Matchi
   end
 end

data/lib/fix/requirement.rb

@@ -14,7 +14,7 @@ module Fix
     # This method mean that the definition is an absolute requirement of the
     # specification.
     #
-    # @param matcher [#matches?] The matcher.
+    # @param matcher [#match?] The matcher.
     #
     # @return [Requirement::Required] An absolute requirement level instance.
     #
@@ -25,7 +25,7 @@ module Fix
 
     # This method mean that the definition is an absolute prohibition of the specification.
     #
-    # @param matcher [#matches?] The matcher.
+    # @param matcher [#match?] The matcher.
     #
     # @return [Requirement::Required] An absolute prohibition level instance.
     #
@@ -38,7 +38,7 @@ module Fix
     # circumstances to ignore a particular item, but the full implications must be
     # understood and carefully weighed before choosing a different course.
     #
-    # @param matcher [#matches?] The matcher.
+    # @param matcher [#match?] The matcher.
     #
     # @return [Requirement::Recommended] A recommended requirement level instance.
     #
@@ -52,7 +52,7 @@ module Fix
     # the full implications should be understood and the case carefully weighed
     # before implementing any behavior described with this label.
     #
-    # @param matcher [#matches?] The matcher.
+    # @param matcher [#match?] The matcher.
     #
     # @return [Requirement::Recommended] A not recommended requirement level
     #   instance.
@@ -73,7 +73,7 @@ module Fix
     # implementation which does not include the option (except, of course, for the
     # feature the option provides).
     #
-    # @param matcher [#matches?] The matcher.
+    # @param matcher [#match?] The matcher.
     #
     # @return [Requirement::Optional] An optional requirement level instance.
     #

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fix
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta10
+  version: 1.0.0.beta12
 platform: ruby
 authors:
 - Cyril Kato
 bindir: bin
 cert_chain: []
-date: 2024-12-24 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -29,28 +29,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.3.2
+        version: 4.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.3.2
+        version: 4.1.0
 - !ruby/object:Gem::Dependency
   name: spectus
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 5.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 5.0.1
 description: Specing framework.
 email: contact@cyril.email
 executables: []