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.

• Ruby >= 3.1.0

Add to your Gemfile:

gem "fix"

Then execute:

bundle install

Or install it yourself:

gem install fix

• 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.

Define reusable properties across your specifications:

Fix do
  let(:name) { "Bob" }
  let(:age) { 42 }

  it MUST eq name
end

Test behavior under different conditions:

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

Test how objects respond to specific messages:

Fix do
  on :upcase do
    it MUST eq "HELLO"
  end

  on :+, 2 do
    it MUST eq 42
  end
end

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

Fix do
  it MUST be_valid           # Required
  it SHOULD be_optimized     # Recommended
  it MAY include_metadata    # Optional
end

Create your first test file:

# first_test.rb
require "fix"

Fix :HelloWorld do
  it MUST eq "Hello, World!"
end

Fix[:HelloWorld].test { "Hello, World!" }

Run it:

ruby first_test.rb

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:

Here's a comprehensive example showing how to specify a user account system:

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

The implementation might look like this:

class User
  attr_reader :role, :password_hash

  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

Here's how Fix can be used to specify a Duck class:

Fix :Duck do
  it SHOULD be_an_instance_of :Duck

  on :swims do
    it MUST be_an_instance_of :String
    it MUST eql "Swoosh..."
  end

  on :speaks do
    it MUST raise_exception NoMethodError
  end

  on :sings do
    it MAY eql "♪... ♫..."
  end
end

The implementation:

class Duck
  def walks
    "Klop klop!"
  end

  def swims
    "Swoosh..."
  end

  def quacks
    puts "Quaaaaaack!"
  end
end

Running the test:

Fix[:Duck].test { Duck.new }

Fix includes a comprehensive set of matchers through its integration with the Matchi library:

Here's an example using various matchers together:

Fix :Calculator do
  it MUST be_an_instance_of Calculator

  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

  with string_input: "123" do
    on :parse do
      it MUST be_a_kind_of Numeric
      it MUST satisfy { |n| n > 0 }
    end
  end
end

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

Ready to write better specifications? Visit our GitHub repository to start using Fix in your Ruby projects.

• Blog - Related articles
• Bluesky - Latest updates and discussions
• Documentation - Comprehensive guides and API reference
• Source Code - Contribute and report issues
• asciinema - Watch practical examples in action

Fix follows Semantic Versioning 2.0.

The gem is available as open source under the terms of the MIT License.

This project is sponsored by Sashité