fix 1.0.0.beta10 → 1.0.0.beta11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af0a01072f39d7c105aff0bde77c97ce31c9aae8a1144e29a00b9098017cb436
-  data.tar.gz: cab7ff1e39fc58599b712ff53597534535e86bf1422f0f10c926e14d1e267e3f
+  metadata.gz: 40461f87067aa8b719fc25a6256772961b8ef4c412cd043ddddc51d8b048d014
+  data.tar.gz: ad050718de8cd7c7fcede3f8c9644b91c33ec2cef4e877fd28773d576b265292
 SHA512:
-  metadata.gz: 90f831b90a8faaabf56db03f17d03905e6c41eb18e0f1873db78e0de30540e46b4b395c7fb19f80b3ccbc6b3e560978c42fb0ff8066b6b912151f2785249b51b
-  data.tar.gz: 4b1f58e67584042977f803b53119d090e76f9848b6b470a86aeefaa5f5a195afe11f3ab98d3383e1c5e1e819ff570b890bff58aa734d2c19c6e3079d75a95ffd
+  metadata.gz: 8d83f640bb5a086f530265eea8fab350a74e4209072aae351107b0fab393e6ebb1f3fcd266550fccc3c21cf5b9885e2444731ab28200861fcc06fff4f3facf83
+  data.tar.gz: 85a1b557e06c39c82c653e4283c0489a6bfb3aec0dff69e1f42617cf93805fe5fbe8ea9a5feb13a853d1969a63ea741c73ba1872b4b8b1939b924e388e0ec377

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.beta11"
 ```
 
 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`
 
-Specifications for a `Duck` class:
+Test how objects respond to specific messages:
 
 ```ruby
-# examples/duck/fix.rb
+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:
+
+- **MUST/MUST_NOT**: Absolute requirements or prohibitions
+- **SHOULD/SHOULD_NOT**: Recommended practices with valid exceptions
+- **MAY**: Optional features
+
+```ruby
+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,31 @@ end
 Running the test:
 
 ```ruby
-# examples/duck/test.rb
-
-require_relative "app"
-require_relative "fix"
-
 Fix[:Duck].test { Duck.new }
 ```
 
-Execute:
+## Why Choose Fix?
 
-```sh
-ruby examples/duck/test.rb
-```
+Fix brings several unique advantages to Ruby testing that set it apart from traditional testing frameworks:
 
-Expected output:
+- **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
 
-```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>.
-```
+## Get Started
+
+Ready to write better specifications? Visit our [GitHub repository](https://github.com/fixrb/fix) to start using Fix in your Ruby projects.
 
-## Contact
+## 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 +257,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

@@ -11,12 +11,12 @@ module Fix
     #
     # @example
     #   matcher = eq("foo")
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
+    #   matcher.match? { "foo" } # => true
+    #   matcher.match? { "bar" } # => false
     #
     # @param expected [#eql?] An expected equivalent object.
     #
-    # @return [#matches?] An equivalence matcher.
+    # @return [#match?] An equivalence matcher.
     #
     # @api public
     def eq(expected)
@@ -30,12 +30,12 @@ module Fix
     # @example
     #   object = "foo"
     #   matcher = be(object)
-    #   matcher.matches? { object } # => true
-    #   matcher.matches? { "foo" } # => false
+    #   matcher.match? { object } # => true
+    #   matcher.match? { "foo" } # => false
     #
     # @param expected [#equal?] The expected identical object.
     #
-    # @return [#matches?] An identity matcher.
+    # @return [#match?] An identity matcher.
     #
     # @api public
     def be(expected)
@@ -48,12 +48,12 @@ module Fix
     #
     # @example
     #   matcher = be_within(1).of(41)
-    #   matcher.matches? { 42 } # => true
-    #   matcher.matches? { 43 } # => false
+    #   matcher.match? { 42 } # => true
+    #   matcher.match? { 43 } # => false
     #
     # @param delta [Numeric] A numeric value.
     #
-    # @return [#matches?] A comparison matcher.
+    # @return [#match?] A comparison matcher.
     #
     # @api public
     def be_within(delta)
@@ -64,12 +64,12 @@ module Fix
     #
     # @example
     #   matcher = match(/^foo$/)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { "bar" } # => false
+    #   matcher.match? { "foo" } # => true
+    #   matcher.match? { "bar" } # => false
     #
     # @param expected [#match] A regular expression.
     #
-    # @return [#matches?] A regular expression matcher.
+    # @return [#match?] A regular expression matcher.
     #
     # @api public
     def match(expected)
@@ -80,12 +80,12 @@ module Fix
     #
     # @example
     #   matcher = raise_exception(NameError)
-    #   matcher.matches? { Boom } # => true
-    #   matcher.matches? { true } # => false
+    #   matcher.match? { Boom } # => true
+    #   matcher.match? { true } # => false
     #
     # @param expected [Exception, #to_s] The expected exception name.
     #
-    # @return [#matches?] An error matcher.
+    # @return [#match?] An error matcher.
     #
     # @api public
     def raise_exception(expected)
@@ -96,12 +96,12 @@ module Fix
     #
     # @example
     #   matcher = be_true
-    #   matcher.matches? { true } # => true
-    #   matcher.matches? { false } # => false
-    #   matcher.matches? { nil } # => false
-    #   matcher.matches? { 4 } # => false
+    #   matcher.match? { true } # => true
+    #   matcher.match? { false } # => false
+    #   matcher.match? { nil } # => false
+    #   matcher.match? { 4 } # => false
     #
-    # @return [#matches?] A `true` matcher.
+    # @return [#match?] A `true` matcher.
     #
     # @api public
     def be_true
@@ -112,12 +112,12 @@ module Fix
     #
     # @example
     #   matcher = be_false
-    #   matcher.matches? { false } # => true
-    #   matcher.matches? { true } # => false
-    #   matcher.matches? { nil } # => false
-    #   matcher.matches? { 4 } # => false
+    #   matcher.match? { false } # => true
+    #   matcher.match? { true } # => false
+    #   matcher.match? { nil } # => false
+    #   matcher.match? { 4 } # => false
     #
-    # @return [#matches?] A `false` matcher.
+    # @return [#match?] A `false` matcher.
     #
     # @api public
     def be_false
@@ -128,12 +128,12 @@ module Fix
     #
     # @example
     #   matcher = be_nil
-    #   matcher.matches? { nil } # => true
-    #   matcher.matches? { false } # => false
-    #   matcher.matches? { true } # => false
-    #   matcher.matches? { 4 } # => false
+    #   matcher.match? { nil } # => true
+    #   matcher.match? { false } # => false
+    #   matcher.match? { true } # => false
+    #   matcher.match? { 4 } # => false
     #
-    # @return [#matches?] A `nil` matcher.
+    # @return [#match?] A `nil` matcher.
     #
     # @api public
     def be_nil
@@ -144,12 +144,12 @@ module Fix
     #
     # @example
     #   matcher = be_an_instance_of(String)
-    #   matcher.matches? { "foo" } # => true
-    #   matcher.matches? { 4 } # => false
+    #   matcher.match? { "foo" } # => true
+    #   matcher.match? { 4 } # => false
     #
     # @param expected [Class, #to_s] The expected class name.
     #
-    # @return [#matches?] A type/class matcher.
+    # @return [#match?] A type/class matcher.
     #
     # @api public
     def be_an_instance_of(expected)
@@ -161,28 +161,28 @@ module Fix
     # @example
     #   object = []
     #   matcher = change(object, :length).by(1)
-    #   matcher.matches? { object << 1 } # => true
+    #   matcher.match? { object << 1 } # => true
     #
     #   object = []
     #   matcher = change(object, :length).by_at_least(1)
-    #   matcher.matches? { object << 1 } # => true
+    #   matcher.match? { object << 1 } # => true
     #
     #   object = []
     #   matcher = change(object, :length).by_at_most(1)
-    #   matcher.matches? { object << 1 } # => true
+    #   matcher.match? { object << 1 } # => true
     #
     #   object = "foo"
     #   matcher = change(object, :to_s).from("foo").to("FOO")
-    #   matcher.matches? { object.upcase! } # => true
+    #   matcher.match? { object.upcase! } # => true
     #
     #   object = "foo"
     #   matcher = change(object, :to_s).to("FOO")
-    #   matcher.matches? { object.upcase! } # => true
+    #   matcher.match? { object.upcase! } # => true
     #
     # @param object [#object_id]  An object.
     # @param method [Symbol]      The name of a method.
     #
-    # @return [#matches?] A change matcher.
+    # @return [#match?] A change matcher.
     #
     # @api public
     def change(object, method, ...)
@@ -193,13 +193,13 @@ module Fix
     #
     # @example
     #   matcher = satisfy { |value| value == 42 }
-    #   matcher.matches? { 42 } # => true
+    #   matcher.match? { 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.
+    # @return [#match?] A satisfy matcher.
     #
     # @api public
     def satisfy(&)
@@ -212,8 +212,8 @@ module Fix
     #
     # @example Empty predicate matcher
     #   matcher = be_empty
-    #   matcher.matches? { [] } # => true
-    #   matcher.matches? { [4] } # => false
+    #   matcher.match? { [] } # => true
+    #   matcher.match? { [4] } # => false
     def method_missing(name, ...)
       return super unless predicate_matcher_name?(name)
 

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.beta11
 platform: ruby
 authors:
 - Cyril Kato
 bindir: bin
 cert_chain: []
-date: 2024-12-24 00:00:00.000000000 Z
+date: 2024-12-30 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.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.3.2
+        version: 4.0.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: []