Fixrb
The Three Levels of Requirements Inspired by RFC 2119
How Fix implements the MUST, SHOULD and MAY requirement levels for more precise specifications, and how this compares with RSpec’s historical evolution.
The main gem of Fixrb
Fix
Specifications for Ruby, in the words of RFC 2119, tested against any subject.
A specification says what a subject MUST, SHOULD or MAY do, and nothing about how it is made. Write it once, then test an Array against it today, your own class tomorrow, a library you depend on, or the next version of any of them.
- Install
gem install fix- Version
- 1.0.0, for Ruby 3.3 or later
- Source
- github.com/fixrb/fix, MIT license
require "fix"
# A stack, whatever it is made of.
Fix :Stack do
on :push, 1 do
on :pop do
it MUST eq 1
end
end
on :pop do
it SHOULD be_nil
end
on :peek do
it MAY be_nil
end
end
# A test picks the subject: an Array.
exit(Fix[:Stack].test { [] })
ruby stack.rb stack.rb:7: Success: expected 1 to eq 1 stack.rb:12: Success: expected nil to be nil stack.rb:16: Info: NoMethodError: undefined method 'peek' for an instance of Array
What makes Fix different
-
A specification is a document
It is read once, when the file is loaded: no setup, no mock, no logic, and anything wrong in it raises before a test runs. It names no class; the test picks the subject.
-
Three levels of requirement
MUST, SHOULD and MAY tell what is required, what is recommended and what is optional. A SHOULD not met is a warning, a MAY on a method the subject lacks is an info, and both pass.
-
One process per context
Each context runs in a child process. What a subject does to a global, a constant or
ENVstays in its context, and the order of the contexts cannot change a result.
The gems
Fix is built from small libraries and extended by small gems. Each does one thing, in a few hundred lines of code at most, so that you can read it before you trust it.
Around Fix
Gems that extend Fix, or bring its specifications to other test frameworks.
-
fix-its
Adds the word
itsto specifications: a method of the subject and its expectation on one line.Version 1.0
-
matchi-fix
A matcher of matchi that tests a value against a specification of Fix, from any test framework.
Version 4.0
-
fix-command
The
fixcommand, to run specification files.Moving to Fix 1.0
Libraries
Building blocks that do not depend on Fix: use them on their own, with any test framework, or to build one. Fix 1.0 is built on spectus, matchi and aw.
-
matchiMatchers for any test framework, in which the expected value makes the comparison, not the object under test.
Version 6.0
-
spectus
Expectations with the requirement levels of RFC 2119, MUST, SHOULD and MAY, that give a result instead of raising. The engine of Fix 1.0, built on defi.
Version 6.0
-
awRuns a block in a forked process and returns its result. Fix 1.0 uses it to keep contexts apart.
Version 1.0
-
defi
Prepares a method call, a name and its arguments, to send to any object and keep what came back.
Version 4.0
-
test_tube
Checks a value, or what a block returns or raises, against a matcher. Built on defi.
Version 4.0
-
expresenter
Presents the result of an expectation: success, warning, info, failure or error.
Version 1.5
Tools
A command to run as it is, rather than a library to build on.
-
brutalWrites plain Ruby test files from a YAML manifest, by recording what the code returns in every combination of contexts. Built on aw.
Version 2.0
From the blog
-
-
Rethinking Test Architecture with Clear Specification Separation
How Fix’s approach to testing in Ruby keeps specifications apart from their implementations, for a test suite that is easier to maintain and to reuse.
-
The Fundamental Distinction Between Expected and Actual Values in Testing
Explore why the distinction between expected and actual values is crucial in test design, and how it impacts the robustness and reliability of your test suite.