fix 0.18.2 → 0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3185bfc9a8b56c3a47a7efbbcbf141ea054e405bf2d4c6d0e76ceec8bc0fed2
-  data.tar.gz: fff9e1401b1e7aff1b9214692922eb6176548f12b94265d673fc4daa311bba53
+  metadata.gz: 9e44836a2e867dcb513bc3daffa30c6c319e18602be1c4cf0e098d14f7ae4f9b
+  data.tar.gz: 70029c70b7efd078c5d4cafdcdacd1921a2c081e1637f7f2cbc867bfde839781
 SHA512:
-  metadata.gz: 7de8da736c7d22d71a24b0d4a03fc691e34f2c33bf1394aeda3a78856b687c6e686b1b4ac548c7a52237953996fb70e35de5733da715a2b06342654ae9737fd2
-  data.tar.gz: 1058e6255fb4423d8479eddf1d95431de023acacefe84d87825f33ed4205378b5eea2ddfcdeb3b72aaa9e921eb96df240e52a12a55427d7dba9b68227550fb02
+  metadata.gz: f18450b4cc887e269471c529e95816537f620e342733a3441091b01709feaf44d7f1fe46e7ea2b228f5eca154f410de0e03456f238aa642e2a35ff1d55aa5376
+  data.tar.gz: 3854f42a81ddece26f7e9b7d33d347caf37c885cb65ea1e17910032c279c249aefa6ff73d3b7dccfd205d5824812d72564c79d2b76cc7d0afd2e2c51ad08428e

data/LICENSE.md

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+# The MIT License
 
-Copyright (c) 2014-2019 Cyril Kato
+Copyright (c) 2014-2025 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,152 +1,452 @@
-# Fix
+# Fix Framework
 
-[![Build Status](https://travis-ci.org/fixrb/fix.svg?branch=master)][travis]
-[![Code Climate](https://codeclimate.com/github/fixrb/fix/badges/gpa.svg)][codeclimate]
-[![Gem Version](https://badge.fury.io/rb/fix.svg)][gem]
-[![Inline docs](http://inch-ci.org/github/fixrb/fix.svg?branch=master)][inchpages]
-[![Documentation](http://img.shields.io/:yard-docs-38c800.svg)][rubydoc]
-[![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
+[![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)
+[![License](https://img.shields.io/github/license/fixrb/fix?label=License&logo=github)](https://github.com/fixrb/fix/raw/main/LICENSE.md)
 
-> Specing framework for Ruby.
+## Introduction
 
-## Contact
-
-* Home page: https://fixrb.dev/
-* Bugs/issues: https://github.com/fixrb/fix/issues
-* Support: https://stackoverflow.com/questions/tagged/fixrb
+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 this line to your application's Gemfile:
+### Prerequisites
+
+- Ruby >= 3.1.0
+
+### Setup
+
+Add to your Gemfile:
 
 ```ruby
-gem 'fix'
+gem "fix"
 ```
 
-And then execute:
+Then execute:
 
-    $ bundle
+```sh
+bundle install
+```
 
-Or install it yourself as:
+Or install it yourself:
 
-    $ gem install fix
+```sh
+gem install fix
+```
 
-## Let's get started!
+## Core Principles
 
-[![asciicast](https://asciinema.org/a/29098.png)](https://asciinema.org/a/29098)
+- **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.
 
-## Philosophy
+- **Logic-Free Specifications**: Your specification documents remain pure and focused on defining behaviors, without getting cluttered by implementation logic.
 
-### Simple, stupid
+- **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.
 
-With 174 LOC built on top of [Spectus expectation library](https://github.com/fixrb/spectus), facilities such as benchmarking and mocking are not supported.  __Fix__ offers however a **consistent** DSL to focus your BDD.
+- **Fast Individual Testing**: Tests execute quickly and independently, providing rapid feedback on specification compliance.
 
-### True specifications
+## Framework Features
 
-While specs behave like **documents** which can be logic-less, their interpretation should not be questioned regardless of the version of __Fix__, preventing from software erosion.  Also, Fix specs are compliant with **[RFC 2119](http://tools.ietf.org/html/rfc2119)**.
+### Property Definition with `let`
 
-### Low code complexity
+Define reusable properties across your specifications:
 
-Monkey-patching, [magic tricks and friends](http://blog.arkency.com/2013/06/are-we-abusing-at-exit/) are not included.  Instead, animated by **authentic** and **unmuted** Ruby objects, unambiguous, understandable and structured specs are encouraged.
+```ruby
+Fix do
+  let(:name) { "Bob" }
+  let(:age) { 42 }
 
-### Test in isolation
+  it MUST eq name
+end
+```
 
-Rather than a _random order_ option to help finding bugs somewhere (and sometimes luck), __Fix__ prevents from **side effects** by running each context inside a distinct **sub-process**.  As it behaves like a function, no matter how many times you call it, the build status remains the same.
+### Context Creation with `with`
 
-## Usage
+Test behavior under different conditions:
 
-Given this app:
+```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
-# duck.rb
-class Duck
-  def walks
-    'Klop klop!'
+Fix do
+  on :upcase do
+    it MUST eq "HELLO"
   end
 
-  def swims
-    'Swoosh...'
+  on :+, 2 do
+    it MUST eq 42
   end
+end
+```
 
-  def quacks
-    puts 'Quaaaaaack!'
+### 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
 ```
 
-When you run this:
+The implementation might look like this:
 
 ```ruby
-# duck_spec.rb
-require_relative 'duck'
-require 'fix'
+class User
+  attr_reader :role, :password_hash
 
-@bird = Duck.new
+  def initialize(role:)
+    @role = role
+    @password_hash = nil
+  end
+
+  def admin?
+    role == "admin"
+  end
+
+  def can_access?(resource)
+    return true if admin?
+    false
+  end
+
+  def full_name
+    "#{@first_name} #{@last_name}"
+  end
+
+  def update_password(new_password)
+    @password_hash = Digest::SHA256.hexdigest(new_password)
+    true
+  end
+end
+```
+
+### 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
 
-Fix.describe @bird do
   on :swims do
-    it { MUST eql 'Swoosh...' }
+    it MUST be_an_instance_of :String
+    it MUST eql "Swoosh..."
   end
 
   on :speaks do
-    it { MUST raise_exception NoMethodError }
+    it MUST raise_exception NoMethodError
   end
 
   on :sings do
-    it { MAY eql '♪... ♫...' }
+    it MAY eql "♪... ♫..."
+  end
+end
+```
+
+The implementation:
+
+```ruby
+class Duck
+  def walks
+    "Klop klop!"
+  end
+
+  def swims
+    "Swoosh..."
+  end
+
+  def quacks
+    puts "Quaaaaaack!"
   end
 end
 ```
 
-Then the output should look like this:
+Running the test:
 
-    $ ruby duck_spec.rb
-    ..I
+```ruby
+Fix[:Duck].test { Duck.new }
+```
+## Available Matchers
+
+Fix includes a comprehensive set of matchers through its integration with the [Matchi library](https://github.com/fixrb/matchi):
+
+<details>
+<summary><strong>Basic Comparison Matchers</strong></summary>
+
+- `eq(expected)` - Tests equality using `eql?`
+  ```ruby
+  it MUST eq(42)                   # Passes if value.eql?(42)
+  it MUST eq("hello")              # Passes if value.eql?("hello")
+  ```
+- `eql(expected)` - Alias for eq
+- `be(expected)` - Tests object identity using `equal?`
+  ```ruby
+  string = "test"
+  it MUST be(string)               # Passes only if it's exactly the same object
+  ```
+- `equal(expected)` - Alias for be
+</details>
+
+<details>
+<summary><strong>Type Checking Matchers</strong></summary>
+
+- `be_an_instance_of(class)` - Verifies exact class match
+  ```ruby
+  it MUST be_an_instance_of(Array) # Passes if value.instance_of?(Array)
+  it MUST be_an_instance_of(User)  # Passes if value.instance_of?(User)
+  ```
+- `be_a_kind_of(class)` - Checks class inheritance and module inclusion
+  ```ruby
+  it MUST be_a_kind_of(Enumerable) # Passes if value.kind_of?(Enumerable)
+  it MUST be_a_kind_of(Animal)     # Passes if value inherits from Animal
+  ```
+</details>
+
+<details>
+<summary><strong>Change Testing Matchers</strong></summary>
+
+- `change(object, method)` - Base matcher for state changes
+  - `.by(n)` - Expects exact change by n
+    ```ruby
+    it MUST change(user, :points).by(5)          # Exactly +5 points
+    ```
+  - `.by_at_least(n)` - Expects minimum change by n
+    ```ruby
+    it MUST change(counter, :value).by_at_least(10)  # At least +10
+    ```
+  - `.by_at_most(n)` - Expects maximum change by n
+    ```ruby
+    it MUST change(account, :balance).by_at_most(100) # No more than +100
+    ```
+  - `.from(old).to(new)` - Expects change from old to new value
+    ```ruby
+    it MUST change(user, :status).from("pending").to("active")
+    ```
+  - `.to(new)` - Expects change to new value
+    ```ruby
+    it MUST change(post, :title).to("Updated")
+    ```
+</details>
+
+<details>
+<summary><strong>Numeric Matchers</strong></summary>
+
+- `be_within(delta).of(value)` - Tests if a value is within ±delta of expected value
+  ```ruby
+  it MUST be_within(0.1).of(3.14)  # Passes if value is between 3.04 and 3.24
+  it MUST be_within(5).of(100)     # Passes if value is between 95 and 105
+  ```
+</details>
+
+<details>
+<summary><strong>Pattern Matchers</strong></summary>
+
+- `match(regex)` - Tests string against regular expression pattern
+  ```ruby
+  it MUST match(/^\d{3}-\d{2}-\d{4}$/)  # SSN format
+  it MUST match(/^[A-Z][a-z]+$/)        # Capitalized word
+  ```
+- `satisfy { |value| ... }` - Custom matching with block
+  ```ruby
+  it MUST satisfy { |num| num.even? && num > 0 }
+  it MUST satisfy { |user| user.valid? && user.active? }
+  ```
+</details>
+
+<details>
+<summary><strong>Exception Matchers</strong></summary>
+
+- `raise_exception(class)` - Tests if code raises specified exception
+  ```ruby
+  it MUST raise_exception(ArgumentError)
+  it MUST raise_exception(CustomError, "specific message")
+  ```
+</details>
+
+<details>
+<summary><strong>State Matchers</strong></summary>
+
+- `be_true` - Tests for true
+  ```ruby
+  it MUST be_true          # Only passes for true, not truthy values
+  ```
+- `be_false` - Tests for false
+  ```ruby
+  it MUST be_false         # Only passes for false, not falsey values
+  ```
+- `be_nil` - Tests for nil
+  ```ruby
+  it MUST be_nil           # Passes only for nil
+  ```
+</details>
+
+<details>
+<summary><strong>Dynamic Predicate Matchers</strong></summary>
+
+- `be_*` - Dynamically matches `object.*?` method
+  ```ruby
+  it MUST be_empty         # Calls empty?
+  it MUST be_valid         # Calls valid?
+  it MUST be_frozen        # Calls frozen?
+  ```
+- `have_*` - Dynamically matches `object.has_*?` method
+  ```ruby
+  it MUST have_key(:id)    # Calls has_key?
+  it MUST have_errors      # Calls has_errors?
+  it MUST have_permission  # Calls has_permission?
+  ```
+</details>
+
+### Complete Example
+
+Here's an example using various matchers together:
 
-    1. Info: undefined method `sings' for #<Duck:0x007fb60383b740> (NoMethodError).
+```ruby
+Fix :Calculator do
+  it MUST be_an_instance_of Calculator
 
-    Ran 3 tests in 0.00038 seconds
-    100% compliant - 1 infos, 0 failures, 0 errors
+  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
 
-## Security
+  with numbers: [1, 2, 3] do
+    it MUST_NOT be_empty
+    it MUST satisfy { |result| result.all? { |n| n.positive? } }
+  end
+
+  with string_input: "123" do
+    on :parse do
+      it MUST be_a_kind_of Numeric
+      it MUST satisfy { |n| n > 0 }
+    end
+  end
+end
+```
 
-As a basic form of security __Fix__ provides a set of SHA512 checksums for
-every Gem release.  These checksums can be found in the `checksum/` directory.
-Although these checksums do not prevent malicious users from tampering with a
-built Gem they can be used for basic integrity verification purposes.
+## Why Choose Fix?
 
-The checksum of a file can be checked using the `sha512sum` command.  For
-example:
+Fix brings several unique advantages to Ruby testing that set it apart from traditional testing frameworks:
 
-    $ sha512sum pkg/fix-0.1.0.gem
-    d12d7d9c2a4fdfe075cbb7a141fa5f2195175891e4098c7e1a28c8bca655ab44fb9d67b6a2e3991d0f852026c5e4537fdf7e314575c68d1c80b3a4b1eb1c041f  pkg/fix-0.1.0.gem
+- **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
 
-## Versioning
+## Get Started
 
-__Fix__ follows [Semantic Versioning 2.0](http://semver.org/).
+Ready to write better specifications? Visit our [GitHub repository](https://github.com/fixrb/fix) to start using Fix in your Ruby projects.
 
-## Contributing
+## Community & Resources
 
-1. [Fork it](https://github.com/fixrb/fix/fork)
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+- [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
 
-## License
+## Versioning
 
-See `LICENSE.md` file.
+__Fix__ follows [Semantic Versioning 2.0](https://semver.org/).
 
-[gem]: https://rubygems.org/gems/fix
-[travis]: https://travis-ci.org/fixrb/fix
-[codeclimate]: https://codeclimate.com/github/fixrb/fix
-[gemnasium]: https://gemnasium.com/fixrb/fix
-[inchpages]: http://inch-ci.org/github/fixrb/fix
-[rubydoc]: http://rubydoc.info/gems/fix/frames
-[gitter]: https://gitter.im/fixrb/fix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
+## License
 
-***
+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).
 
-This project is sponsored by:
+## Sponsors
 
-[![Sashite](https://pbs.twimg.com/profile_images/618485028322975744/PZ9qPuI__400x400.png)](https://sashite.com/)
+This project is sponsored by [Sashité](https://sashite.com/)

data/lib/fix/builder.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "doc"
+require_relative "dsl"
+require_relative "set"
+require_relative "error/missing_specification_block"
+
+module Fix
+  # Handles the creation and setup of Fix specifications.
+  #
+  # The Builder constructs new Fix specification sets following these steps:
+  # 1. Creates a new specification class inheriting from DSL
+  # 2. Defines the specification content using the provided block
+  # 3. Optionally registers the named specification
+  # 4. Returns the built specification set
+  #
+  # @example Create a named specification
+  #   Fix::Builder.build(:Calculator) do
+  #     on(:add, 2, 3) { it MUST equal 5 }
+  #   end
+  #
+  # @example Create an anonymous specification
+  #   Fix::Builder.build do
+  #     it MUST be_positive
+  #   end
+  #
+  # @see Fix::Set
+  # @see Fix::Dsl
+  # @api private
+  class Builder
+    # Creates a new specification set.
+    #
+    # @param name [String, Symbol, nil] Optional name for the specification
+    # @yieldparam [void] Block containing specification definitions
+    # @yieldreturn [void]
+    # @return [Fix::Set] The constructed specification set
+    # @raise [Fix::Error::InvalidSpecificationName] If name is invalid
+    # @raise [Fix::Error::MissingSpecificationBlock] If no block given
+    def self.build(name = nil, &block)
+      new(name, &block).construct_set
+    end
+
+    # @return [String, Symbol, nil] The name of the specification
+    attr_reader :name
+
+    def initialize(name = nil, &block)
+      raise Error::MissingSpecificationBlock unless block
+
+      @name = name
+      @block = block
+    end
+
+    # Constructs and returns a new specification set.
+    #
+    # @return [Fix::Set] The constructed specification set
+    def construct_set
+      klass = create_specification
+      populate_specification(klass)
+      register_if_named(klass)
+      build_set(klass)
+    end
+
+    private
+
+    # @return [Proc] The block containing specification definitions
+    attr_reader :block
+
+    # Creates a new specification class with context tracking.
+    #
+    # @return [Class] A new class inheriting from Fix::Dsl with CONTEXTS initialized
+    def create_specification
+      ::Class.new(Dsl).tap do |klass|
+        klass.const_set(:CONTEXTS, [klass])
+      end
+    end
+
+    # Evaluates the specification block in the context of the class.
+    #
+    # @param klass [Class] The class to populate with specifications
+    # @return [void]
+    def populate_specification(klass)
+      klass.instance_eval(&block)
+    end
+
+    # Registers the specification in Fix::Doc if a name was provided.
+    #
+    # @param klass [Class] The specification class to register
+    # @return [void]
+    def register_if_named(klass)
+      Doc.spec_set(name, klass) if name
+    end
+
+    # Creates a new specification set from the populated class.
+    #
+    # @param klass [Class] The populated specification class
+    # @return [Fix::Set] A new specification set
+    def build_set(klass)
+      Set.new(*klass.const_get(:CONTEXTS))
+    end
+  end
+end