{"id":21502404,"url":"https://github.com/fixrb/spectus","last_synced_at":"2025-06-24T08:32:36.614Z","repository":{"id":21021315,"uuid":"24314575","full_name":"fixrb/spectus","owner":"fixrb","description":"Expectation library with RFC 2119's requirement levels 🚥","archived":false,"fork":false,"pushed_at":"2025-01-01T00:17:44.000Z","size":1680,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-28T21:36:09.118Z","etag":null,"topics":["expectation","ruby","spec"],"latest_commit_sha":null,"homepage":"","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":"2014-09-22T04:44:42.000Z","updated_at":"2025-01-01T00:17:48.000Z","dependencies_parsed_at":"2024-12-30T20:18:56.002Z","dependency_job_id":"eccdd261-20bd-4ce9-8b19-f584e7464abd","html_url":"https://github.com/fixrb/spectus","commit_stats":{"total_commits":209,"total_committers":4,"mean_commits":52.25,"dds":"0.10526315789473684","last_synced_commit":"9cc5b716d3c574aa98ad353d1689a9e056abee0a"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/fixrb/spectus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Fspectus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Fspectus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Fspectus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Fspectus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fixrb","download_url":"https://codeload.github.com/fixrb/spectus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fixrb%2Fspectus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261635565,"owners_count":23187871,"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","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":["expectation","ruby","spec"],"created_at":"2024-11-23T18:14:49.008Z","updated_at":"2025-06-24T08:32:36.598Z","avatar_url":"https://github.com/fixrb.png","language":"Ruby","readme":"# Spectus\n\n[![Version](https://img.shields.io/github/v/tag/fixrb/spectus?label=Version\u0026logo=github)](https://github.com/fixrb/spectus/tags)\n[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/spectus/main)\n[![License](https://img.shields.io/github/license/fixrb/spectus?label=License\u0026logo=github)](https://github.com/fixrb/spectus/raw/main/LICENSE.md)\n\n\u003e A Ruby testing library that brings precision to your expectations using RFC 2119 compliance levels. 🚥\n\n## Quick Start\n\n```ruby\nrequire \"spectus\"\nrequire \"matchi\"\n\n# Define a must-have requirement\ntest = Spectus.must Matchi::Eq.new(42)\ntest.call { 42 } # =\u003e Pass ✅\n\n# Define an optional feature\ntest = Spectus.may Matchi::Be.new(:empty?)\ntest.call { [].empty? } # =\u003e Pass ✅\n```\n\n## Installation\n\nAdd to your Gemfile:\n\n```ruby\ngem \"spectus\"\ngem \"matchi\" # For matchers\n```\n\nOr install directly:\n\n```bash\ngem install spectus\ngem install matchi\n```\n\n## Understanding RFC 2119\n\nSpectus implements [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) requirement levels to bring clarity and precision to test expectations:\n\n- **MUST** (✅): Absolute requirement, no exceptions\n- **SHOULD** (⚠️): Strong recommendation with valid exceptions\n- **MAY** (💡): Optional feature\n\nThis approach helps you clearly communicate the importance of each test in your suite.\n\n## Features\n\n### Requirement Levels\n\n| Level | Description | Pass Conditions |\n|-------|-------------|-----------------|\n| MUST | Absolute requirement | Only when exact match |\n| SHOULD | Recommended behavior | When matches or has valid reason not to |\n| MAY | Optional feature | When matches or not implemented |\n\n### Results Classification\n\n- **Pass Results:**\n  - ✅ Success (MUST level met)\n  - ⚠️ Warning (SHOULD level met)\n  - 💡 Info (MAY level met)\n\n- **Fail Results:**\n  - ❌ Failure (requirement not met)\n  - 💥 Error (unexpected exception)\n\n## Usage Examples\n\n### Testing Required Behavior\n\n```ruby\ntest = Spectus.must Matchi::Be.new(1)\ntest.call { \"🦇\".size } # Must be exactly 1\n```\n\n### Testing Recommended Behavior\n\n```ruby\ntest = Spectus.should Matchi::Be.new(0.3)\ntest.call { 0.1 + 0.2 } # Should be close to 0.3\n```\n\n### Testing Optional Features\n\n```ruby\ntest = Spectus.may Matchi::Be.new(true)\ntest.call { [].blank? } # May implement blank? method\n```\n\n## Advanced Usage\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand custom matcher example\u003c/summary\u003e\n\n```ruby\nclass PositiveNumber\n  def match?\n    yield.positive?\n  end\nend\n\ntest = Spectus.must PositiveNumber.new\ntest.call { 42 } # =\u003e Pass\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand integration example\u003c/summary\u003e\n\n```ruby\nrequire \"spectus\"\nrequire \"matchi\"\n\nRSpec.describe Calculator do\n  it \"must perform exact arithmetic\" do\n    test = Spectus.must Matchi::Eq.new(4)\n    expect { test.call { 2 + 2 } }.not_to raise_error\n  end\nend\n```\n\u003c/details\u003e\n\n## Related Projects\n\n- [Matchi](https://github.com/fixrb/matchi) - Collection of compatible matchers\n- [Test Tube](https://github.com/fixrb/test_tube) - Underlying test execution engine\n- [Expresenter](https://github.com/fixrb/expresenter) - Test result presentation\n\n## License\n\nReleased under the [MIT License](LICENSE.md).\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/fixrb/spectus/issues)\n- Documentation: [RubyDoc](https://rubydoc.info/github/fixrb/spectus/main)\n- Blog Post: [Fix Article](https://fixrb.dev/framework/testing/2024/12/30/the-three-levels-of-requirements-inspired-by-rfc-2119.html)\n\n## Sponsors\n\nThis project is sponsored by [Sashité](https://sashite.com/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffixrb%2Fspectus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffixrb%2Fspectus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffixrb%2Fspectus/lists"}