Spectus

Build Status Gem Version Inline docs Documentation

Expectation library with RFC 2119's requirement levels, and some matchers for Ruby.

Contact

Rubies

Installation

Spectus is cryptographically signed.

To be sure the gem you install hasn't been tampered with, add my public key (if you haven't already) as a trusted certificate:

$ gem cert --add <(curl -Ls https://raw.github.com/fixrb/spectus/master/certs/gem-fixrb-public_cert.pem)
$ gem install spectus -P HighSecurity

The HighSecurity trust profile will verify all gems. All of Spectus's dependencies are signed.

Or add this line to your application's Gemfile:

gem 'spectus'

And then execute:

$ bundle

Expectation

An expectation is an assertion that is either true or false.

Requirement levels MUST SHOULD MAY
Implemented & Matched true true true
Implemented & Not matched false true false
Implemented & Exception false false false
Not implemented false false true

Results

There are two cases:

  • when an expectation is true, an instance of Spectus::Result::Pass is returned;
  • when an expectation is false, an instance of Spectus::Result::Fail is raised.

Both instances share the same interface.

Usage

Absolute requirement

Given the "ルビー" object, when it receives valid_encoding? method, then it MUST be true:

Spectus.this { 'ルビー'.valid_encoding? }.MUST :BeTrue
# => #<Spectus::Result::Pass:0x007f9329c45090 @message="Pass: Expected true to be true.", @subject=#<Proc:0x007f9329c45d60@(irb):1>, @challenge=:call, @context=[], @actual=true, @expected=:BeTrue, @got=true, @error=nil, @level=:High, @negate=false, @valid=true>

The result of the test shows that the spec passed.

Absolute prohibition

Given the "foo" object, when it receives length method, then it MUST NOT raise the NoMethodError exception:

Spectus.this { 'foo'.length }.MUST_NOT RaiseException: NoMethodError
# => #<Spectus::Result::Pass:0x007f9329c341f0 @message="Pass: Expected 3 not to raise exception NoMethodError.", @subject=#<Proc:0x007f9329c34da8@(irb):2>, @challenge=:call, @context=[], @actual=3, @expected={:RaiseException=>NoMethodError}, @got=true, @error=nil, @level=:High, @negate=true, @valid=true>

The result of the test shows that the spec passed.

Given the BasicObject object, when it receives superclass method, then it SHOULD return the explicit blank class NilClass:

Spectus.this { BasicObject.superclass }.SHOULD Equal: NilClass
# => #<Spectus::Result::Pass:0x007f9329c1def0 @message="Info: Expected nil to equal NilClass.", @subject=#<Proc:0x007f9329c1e990@(irb):3>, @challenge=:call, @context=[], @actual=nil, @expected={:Equal=>NilClass}, @got=false, @error=nil, @level=:Medium, @negate=false, @valid=false>

Instead of the expected NilClass class, its sole instance (which is nil) was returned. However, because there isn't any exception, the result of the test shows that the spec passed.

Given the "1" object, when it receives +(1) method, then it SHOULD NOT return the "11" value:

Spectus.this { '1' + 1 }.SHOULD_NOT Eql: '11'
# Spectus::Result::Fail: Error: no implicit conversion of Fixnum into String (TypeError).
#   from (irb):4
#   from ./bin/console:7:in `<main>'

There was a TypeError exception, the result of the test shows that the spec failed.

Optional

Given the "foo" object, when it receives blank? method, then it MAY be false:

Spectus.this { 'foo'.blank? }.MAY :BeFalse
# => #<Spectus::Result::Pass:0x007f932b91feb8 @message="Info: undefined method `blank?' for \"foo\":String (NoMethodError).", @subject=#<Proc:0x007f9329bfc5e8@(irb):5>, @challenge=:call, @context=[], @actual=nil, @expected=:BeFalse, @got=nil, @error=#<NoMethodError: undefined method `blank?' for "foo":String>, @level=:Low, @negate=false, @valid=false>

The optional blank? method is not implemented (unlike in Ruby on Rails, for instance), so the result of the test shows that the spec passed.

Security

As a basic form of security Spectus provides a set of SHA512 checksums for every Gem release. These checksums can be found in the checksum/ directory. Although these checksums do not prevent malicious users from tampering with a built Gem they can be used for basic integrity verification purposes.

The checksum of a file can be checked using the sha512sum command. For example:

$ sha512sum pkg/spectus-2.3.0.gem
d12d7d9c2a4fdfe075cbb7a141fa5f2195175891e4098c7e1a28c8bca655ab44fb9d67b6a2e3991d0f852026c5e4537fdf7e314575c68d1c80b3a4b1eb1c041f  pkg/spectus-2.3.0.gem

Versioning

Spectus follows Semantic Versioning 2.0.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License

See LICENSE.md file.