{"id":21502408,"url":"https://github.com/fixrb/fix","last_synced_at":"2025-10-12T16:34:44.045Z","repository":{"id":48670513,"uuid":"41813937","full_name":"fixrb/fix","owner":"fixrb","description":"Happy Path to Ruby Testing","archived":false,"fork":false,"pushed_at":"2025-01-18T10:37:10.000Z","size":6747,"stargazers_count":48,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-07T17:38:52.091Z","etag":null,"topics":["bdd-framework","ruby","specing-framework"],"latest_commit_sha":null,"homepage":"https://fixrb.dev/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fixrb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-02T16:53:17.000Z","updated_at":"2025-01-03T21:56:44.000Z","dependencies_parsed_at":"2024-01-29T00:30:00.708Z","dependency_job_id":"cfa1416f-5035-46ce-923b-15ac2c668f7a","html_url":"https://github.com/fixrb/fix","commit_stats":{"total_commits":129,"total_committers":2,"mean_commits":64.5,"dds":0.09302325581395354,"last_synced_commit":"e9d8655bebe7fb2fd184f88987069bd5fcf19b32"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/fixrb/fix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Ffix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Ffix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Ffix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Ffix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fixrb","download_url":"https://codeload.github.com/fixrb/fix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Ffix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006334,"owners_count":26084083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bdd-framework","ruby","specing-framework"],"created_at":"2024-11-23T18:14:50.744Z","updated_at":"2025-10-12T16:34:44.028Z","avatar_url":"https://github.com/fixrb.png","language":"Ruby","readme":"# Fix Framework\n\n[![Home](https://img.shields.io/badge/Home-fixrb.dev-00af8b)](https://fixrb.dev/)\n[![Version](https://img.shields.io/github/v/tag/fixrb/fix?label=Version\u0026logo=github)](https://github.com/fixrb/fix/tags)\n[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/fix/main)\n[![License](https://img.shields.io/github/license/fixrb/fix?label=License\u0026logo=github)](https://github.com/fixrb/fix/raw/main/LICENSE.md)\n\n## Introduction\n\nFix 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.\n\n## Installation\n\n### Prerequisites\n\n- Ruby \u003e= 3.1.0\n\n### Setup\n\nAdd to your Gemfile:\n\n```ruby\ngem \"fix\"\n```\n\nThen execute:\n\n```sh\nbundle install\n```\n\nOr install it yourself:\n\n```sh\ngem install fix\n```\n\n## Core Principles\n\n- **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.\n\n- **Logic-Free Specifications**: Your specification documents remain pure and focused on defining behaviors, without getting cluttered by implementation logic.\n\n- **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.\n\n- **Fast Individual Testing**: Tests execute quickly and independently, providing rapid feedback on specification compliance.\n\n## Framework Features\n\n### Property Definition with `let`\n\nDefine reusable properties across your specifications:\n\n```ruby\nFix do\n  let(:name) { \"Bob\" }\n  let(:age) { 42 }\n\n  it MUST eq name\nend\n```\n\n### Context Creation with `with`\n\nTest behavior under different conditions:\n\n```ruby\nFix do\n  with name: \"Alice\", role: \"admin\" do\n    it MUST be_allowed\n  end\n\n  with name: \"Bob\", role: \"guest\" do\n    it MUST_NOT be_allowed\n  end\nend\n```\n\n### Method Testing with `on`\n\nTest how objects respond to specific messages:\n\n```ruby\nFix do\n  on :upcase do\n    it MUST eq \"HELLO\"\n  end\n\n  on :+, 2 do\n    it MUST eq 42\n  end\nend\n```\n\n### Requirement Levels\n\nFix provides three levels of requirements, each with clear semantic meaning:\n\n- **MUST/MUST_NOT**: Absolute requirements or prohibitions\n- **SHOULD/SHOULD_NOT**: Recommended practices with valid exceptions\n- **MAY**: Optional features\n\n```ruby\nFix do\n  it MUST be_valid           # Required\n  it SHOULD be_optimized     # Recommended\n  it MAY include_metadata    # Optional\nend\n```\n\n## Quick Start\n\nCreate your first test file:\n\n```ruby\n# first_test.rb\nrequire \"fix\"\n\nFix :HelloWorld do\n  it MUST eq \"Hello, World!\"\nend\n\nFix[:HelloWorld].test { \"Hello, World!\" }\n```\n\nRun it:\n\n```sh\nruby first_test.rb\n```\n\n## Real-World Examples\n\nFix is designed to work with real-world applications of any complexity. Here are some examples demonstrating how Fix can be used in different scenarios:\n\n### Example 1: User Account Management\n\nHere's a comprehensive example showing how to specify a user account system:\n\n```ruby\nFix :UserAccount do\n  # Define reusable properties\n  let(:admin) { User.new(role: \"admin\") }\n  let(:guest) { User.new(role: \"guest\") }\n\n  # Test basic instance properties\n  it MUST be_an_instance_of User\n\n  # Test with different contexts\n  with role: \"admin\" do\n    it MUST be_admin\n\n    on :can_access?, \"settings\" do\n      it MUST be_true\n    end\n  end\n\n  with role: \"guest\" do\n    it MUST_NOT be_admin\n\n    on :can_access?, \"settings\" do\n      it MUST be_false\n    end\n  end\n\n  # Test specific methods\n  on :full_name do\n    with first_name: \"John\", last_name: \"Doe\" do\n      it MUST eq \"John Doe\"\n    end\n  end\n\n  on :update_password, \"new_password\" do\n    it MUST change(admin, :password_hash)\n    it MUST be_true  # Return value check\n  end\nend\n```\n\nThe implementation might look like this:\n\n```ruby\nclass User\n  attr_reader :role, :password_hash\n\n  def initialize(role:)\n    @role = role\n    @password_hash = nil\n  end\n\n  def admin?\n    role == \"admin\"\n  end\n\n  def can_access?(resource)\n    return true if admin?\n    false\n  end\n\n  def full_name\n    \"#{@first_name} #{@last_name}\"\n  end\n\n  def update_password(new_password)\n    @password_hash = Digest::SHA256.hexdigest(new_password)\n    true\n  end\nend\n```\n\n### Example 2: Duck Specification\n\nHere's how Fix can be used to specify a Duck class:\n\n```ruby\nFix :Duck do\n  it SHOULD be_an_instance_of :Duck\n\n  on :swims do\n    it MUST be_an_instance_of :String\n    it MUST eql \"Swoosh...\"\n  end\n\n  on :speaks do\n    it MUST raise_exception NoMethodError\n  end\n\n  on :sings do\n    it MAY eql \"♪... ♫...\"\n  end\nend\n```\n\nThe implementation:\n\n```ruby\nclass Duck\n  def walks\n    \"Klop klop!\"\n  end\n\n  def swims\n    \"Swoosh...\"\n  end\n\n  def quacks\n    puts \"Quaaaaaack!\"\n  end\nend\n```\n\nRunning the test:\n\n```ruby\nFix[:Duck].test { Duck.new }\n```\n## Available Matchers\n\nFix includes a comprehensive set of matchers through its integration with the [Matchi library](https://github.com/fixrb/matchi):\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBasic Comparison Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `eq(expected)` - Tests equality using `eql?`\n  ```ruby\n  it MUST eq(42)                   # Passes if value.eql?(42)\n  it MUST eq(\"hello\")              # Passes if value.eql?(\"hello\")\n  ```\n- `eql(expected)` - Alias for eq\n- `be(expected)` - Tests object identity using `equal?`\n  ```ruby\n  string = \"test\"\n  it MUST be(string)               # Passes only if it's exactly the same object\n  ```\n- `equal(expected)` - Alias for be\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eType Checking Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `be_an_instance_of(class)` - Verifies exact class match\n  ```ruby\n  it MUST be_an_instance_of(Array) # Passes if value.instance_of?(Array)\n  it MUST be_an_instance_of(User)  # Passes if value.instance_of?(User)\n  ```\n- `be_a_kind_of(class)` - Checks class inheritance and module inclusion\n  ```ruby\n  it MUST be_a_kind_of(Enumerable) # Passes if value.kind_of?(Enumerable)\n  it MUST be_a_kind_of(Animal)     # Passes if value inherits from Animal\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eChange Testing Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `change(object, method)` - Base matcher for state changes\n  - `.by(n)` - Expects exact change by n\n    ```ruby\n    it MUST change(user, :points).by(5)          # Exactly +5 points\n    ```\n  - `.by_at_least(n)` - Expects minimum change by n\n    ```ruby\n    it MUST change(counter, :value).by_at_least(10)  # At least +10\n    ```\n  - `.by_at_most(n)` - Expects maximum change by n\n    ```ruby\n    it MUST change(account, :balance).by_at_most(100) # No more than +100\n    ```\n  - `.from(old).to(new)` - Expects change from old to new value\n    ```ruby\n    it MUST change(user, :status).from(\"pending\").to(\"active\")\n    ```\n  - `.to(new)` - Expects change to new value\n    ```ruby\n    it MUST change(post, :title).to(\"Updated\")\n    ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNumeric Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `be_within(delta).of(value)` - Tests if a value is within ±delta of expected value\n  ```ruby\n  it MUST be_within(0.1).of(3.14)  # Passes if value is between 3.04 and 3.24\n  it MUST be_within(5).of(100)     # Passes if value is between 95 and 105\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePattern Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `match(regex)` - Tests string against regular expression pattern\n  ```ruby\n  it MUST match(/^\\d{3}-\\d{2}-\\d{4}$/)  # SSN format\n  it MUST match(/^[A-Z][a-z]+$/)        # Capitalized word\n  ```\n- `satisfy { |value| ... }` - Custom matching with block\n  ```ruby\n  it MUST satisfy { |num| num.even? \u0026\u0026 num \u003e 0 }\n  it MUST satisfy { |user| user.valid? \u0026\u0026 user.active? }\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eException Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `raise_exception(class)` - Tests if code raises specified exception\n  ```ruby\n  it MUST raise_exception(ArgumentError)\n  it MUST raise_exception(CustomError, \"specific message\")\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eState Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `be_true` - Tests for true\n  ```ruby\n  it MUST be_true          # Only passes for true, not truthy values\n  ```\n- `be_false` - Tests for false\n  ```ruby\n  it MUST be_false         # Only passes for false, not falsey values\n  ```\n- `be_nil` - Tests for nil\n  ```ruby\n  it MUST be_nil           # Passes only for nil\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDynamic Predicate Matchers\u003c/strong\u003e\u003c/summary\u003e\n\n- `be_*` - Dynamically matches `object.*?` method\n  ```ruby\n  it MUST be_empty         # Calls empty?\n  it MUST be_valid         # Calls valid?\n  it MUST be_frozen        # Calls frozen?\n  ```\n- `have_*` - Dynamically matches `object.has_*?` method\n  ```ruby\n  it MUST have_key(:id)    # Calls has_key?\n  it MUST have_errors      # Calls has_errors?\n  it MUST have_permission  # Calls has_permission?\n  ```\n\u003c/details\u003e\n\n### Complete Example\n\nHere's an example using various matchers together:\n\n```ruby\nFix :Calculator do\n  it MUST be_an_instance_of Calculator\n\n  on :add, 2, 3 do\n    it MUST eq 5\n    it MUST be_within(0.001).of(5.0)\n  end\n\n  on :divide, 1, 0 do\n    it MUST raise_exception ZeroDivisionError\n  end\n\n  with numbers: [1, 2, 3] do\n    it MUST_NOT be_empty\n    it MUST satisfy { |result| result.all? { |n| n.positive? } }\n  end\n\n  with string_input: \"123\" do\n    on :parse do\n      it MUST be_a_kind_of Numeric\n      it MUST satisfy { |n| n \u003e 0 }\n    end\n  end\nend\n```\n\n## Why Choose Fix?\n\nFix brings several unique advantages to Ruby testing that set it apart from traditional testing frameworks:\n\n- **Clear Separation of Concerns**: Keep your specifications clean and your examples separate\n- **Semantic Precision**: Express requirements with different levels of necessity\n- **Fast Execution**: Get quick feedback on specification compliance\n- **Pure Specifications**: Write specification documents that focus on behavior, not implementation\n- **Rich Matcher Library**: Comprehensive set of matchers for different testing needs\n- **Modern Ruby**: Takes advantage of modern Ruby features and practices\n\n## Get Started\n\nReady to write better specifications? Visit our [GitHub repository](https://github.com/fixrb/fix) to start using Fix in your Ruby projects.\n\n## Community \u0026 Resources\n\n- [Blog](https://fixrb.dev/) - Related articles\n- [Bluesky](https://bsky.app/profile/fixrb.dev) - Latest updates and discussions\n- [Documentation](https://www.rubydoc.info/gems/fix) - Comprehensive guides and API reference\n- [Source Code](https://github.com/fixrb/fix) - Contribute and report issues\n- [asciinema](https://asciinema.org/~fix) - Watch practical examples in action\n\n## Versioning\n\n__Fix__ follows [Semantic Versioning 2.0](https://semver.org/).\n\n## License\n\nThe [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).\n\n## Sponsors\n\nThis project is sponsored by [Sashité](https://sashite.com/)\n","funding_links":[],"categories":["Testing"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffixrb%2Ffix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffixrb%2Ffix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffixrb%2Ffix/lists"}