https://github.com/fixrb/spectus
Expectation library with RFC 2119's requirement levels 🚥
https://github.com/fixrb/spectus
expectation ruby spec
Last synced: 3 months ago
JSON representation
Expectation library with RFC 2119's requirement levels 🚥
- Host: GitHub
- URL: https://github.com/fixrb/spectus
- Owner: fixrb
- License: mit
- Created: 2014-09-22T04:44:42.000Z (about 11 years ago)
- Default Branch: main
- Last Pushed: 2025-01-01T00:17:44.000Z (9 months ago)
- Last Synced: 2025-05-28T21:36:09.118Z (4 months ago)
- Topics: expectation, ruby, spec
- Language: Ruby
- Homepage:
- Size: 1.6 MB
- Stars: 11
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Spectus
[](https://github.com/fixrb/spectus/tags)
[](https://rubydoc.info/github/fixrb/spectus/main)
[](https://github.com/fixrb/spectus/raw/main/LICENSE.md)
> A Ruby testing library that brings precision to your expectations using RFC 2119 compliance levels. 🚥
## Quick Start
```ruby
require "spectus"
require "matchi"
# Define a must-have requirement
test = Spectus.must Matchi::Eq.new(42)
test.call { 42 } # => Pass ✅
# Define an optional feature
test = Spectus.may Matchi::Be.new(:empty?)
test.call { [].empty? } # => Pass ✅
```
## Installation
Add to your Gemfile:
```ruby
gem "spectus"
gem "matchi" # For matchers
```
Or install directly:
```bash
gem install spectus
gem install matchi
```
## Understanding RFC 2119
Spectus implements [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) requirement levels to bring clarity and precision to test expectations:
- **MUST** (✅): Absolute requirement, no exceptions
- **SHOULD** (⚠️): Strong recommendation with valid exceptions
- **MAY** (💡): Optional feature
This approach helps you clearly communicate the importance of each test in your suite.
## Features
### Requirement Levels
| Level | Description | Pass Conditions |
|-------|-------------|-----------------|
| MUST | Absolute requirement | Only when exact match |
| SHOULD | Recommended behavior | When matches or has valid reason not to |
| MAY | Optional feature | When matches or not implemented |
### Results Classification
- **Pass Results:**
- ✅ Success (MUST level met)
- ⚠️ Warning (SHOULD level met)
- 💡 Info (MAY level met)
- **Fail Results:**
- ❌ Failure (requirement not met)
- 💥 Error (unexpected exception)
## Usage Examples
### Testing Required Behavior
```ruby
test = Spectus.must Matchi::Be.new(1)
test.call { "🦇".size } # Must be exactly 1
```
### Testing Recommended Behavior
```ruby
test = Spectus.should Matchi::Be.new(0.3)
test.call { 0.1 + 0.2 } # Should be close to 0.3
```
### Testing Optional Features
```ruby
test = Spectus.may Matchi::Be.new(true)
test.call { [].blank? } # May implement blank? method
```
## Advanced Usage
Click to expand custom matcher example
```ruby
class PositiveNumber
def match?
yield.positive?
end
end
test = Spectus.must PositiveNumber.new
test.call { 42 } # => Pass
```
Click to expand integration example
```ruby
require "spectus"
require "matchi"
RSpec.describe Calculator do
it "must perform exact arithmetic" do
test = Spectus.must Matchi::Eq.new(4)
expect { test.call { 2 + 2 } }.not_to raise_error
end
end
```
## Related Projects
- [Matchi](https://github.com/fixrb/matchi) - Collection of compatible matchers
- [Test Tube](https://github.com/fixrb/test_tube) - Underlying test execution engine
- [Expresenter](https://github.com/fixrb/expresenter) - Test result presentation
## License
Released under the [MIT License](LICENSE.md).
## Support
- Issues: [GitHub Issues](https://github.com/fixrb/spectus/issues)
- Documentation: [RubyDoc](https://rubydoc.info/github/fixrb/spectus/main)
- Blog Post: [Fix Article](https://fixrb.dev/framework/testing/2024/12/30/the-three-levels-of-requirements-inspired-by-rfc-2119.html)
## Sponsors
This project is sponsored by [Sashité](https://sashite.com/)