Project

spectus

0.01
Low commit activity in last 3 years
A long-lived project that still receives updates
Expectation library with RFC 2119's requirement levels πŸš₯
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Runtime

~> 1.5.1
~> 4.0.1
 Project Readme

Spectus

Version Yard documentation License

A Ruby testing library that brings precision to your expectations using RFC 2119 compliance levels. πŸš₯

Quick Start

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:

gem "spectus"
gem "matchi" # For matchers

Or install directly:

gem install spectus
gem install matchi

Understanding RFC 2119

Spectus implements RFC 2119 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

test = Spectus.must Matchi::Be.new(1)
test.call { "πŸ¦‡".size } # Must be exactly 1

Testing Recommended Behavior

test = Spectus.should Matchi::Be.new(0.3)
test.call { 0.1 + 0.2 } # Should be close to 0.3

Testing Optional Features

test = Spectus.may Matchi::Be.new(true)
test.call { [].blank? } # May implement blank? method

Advanced Usage

Click to expand custom matcher example
class PositiveNumber
  def match?
    yield.positive?
  end
end

test = Spectus.must PositiveNumber.new
test.call { 42 } # => Pass
Click to expand integration example
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

License

Released under the MIT License.

Support

Sponsors

This project is sponsored by SashitΓ©