Matest

![Gitter](https://badges.gitter.im/Join Chat.svg)

Tests Gasoleros (Very cheap tests)

Description

Matest is a very small testing library.

It doesn't use the usual assertion style (assert(1, 1)) nor the rspec style(1.should == 1 or 1.must_equal(1)).

It uses natural assertions.

This means that:

A test will pass if it returns true
A test will fail if it returns false

Usage

To run Matest, you just need to execute the matest command, passing as arguments the desired test files.

$ matest spec/my_spec.rb

You can also use wildcards.

For example, to run all the specs in a directory:

$ matest spec/*_spec.rb

Or to run recursively

$ matest spec/**/*_spec.rb

Specs

To define a test, first you need to set a scope, and inside it, define your spec.

scope do
  spec do
    true
  end
end

If the return value of the spec block is true, the spec will pass and if it's false it will fail.

If you return anithing else, you'll get a NOT A NATURAL ASSERTION status.

You can also add descriptions to either the scope or the spec blocks:

scope "a description" do
  spec "another description" do
    true
  end
end

Constraints

A couple of constraints must b taken into account, and this is extremely important.

The assertion MUST return a boolean

The assertion is the last statement of the block and it must return either true or false. This is important, because the assertion will be evaluated and it will provide the status o the test.

Assertion expression

The assertion can be any expression that returns a boolean value, BUT IT CANNOT CONTAIN LOCAL VARIABLES. If the assertion contains a local variable and it fails, the code that explains it bit by bit will throw an error.

Raising Errors

If your test raises an error during the run, youll get an ERROR status and you'll see the backtrace.

Skipping

You can skip a test in two possible ways: You can declare a spec whithout a block or use the xspec method.

scope do
  spec "I'll be skipped"
  xspec "I'll be skipped too" do
    true
  end
end

This will skip you spec and inform you when you run.

You can skip the whole scope by using xscope instead of scope.

Take into account that xscope is a no-op so you won't be informed when you skip a scope.

`#let` and `#let!`

Matest steals the let and let! features from RSpec and Minitest.

With let you can declare a lazy variable valid on the current scope and all sub-scopes. let! has the same efect, but it won't be lazy (it wil be loaded when defined).

Here are some examples of what you can do with them:

scope do
  let(:m1) { :m1 }
  let!(:m3) { :m3 }
  
  let(:m4) { :m4 }
  let!(:m5) { :m5 }

  spec do
    m1 == :m1
  end

  spec do
    ! defined?(m2)
  end

  spec do
    m3 == :m3
  end

  spec do
    ! defined?(@m4)
  end

  spec do
    !! defined?(@m5)
  end
  
  scope do
    let(:m2) { :m2 }
    spec do
      m1 == :m1
    end

    spec do
      m2 == :m2
    end
  end
end

The output

In case the test fails or is not a natural assertion, you'll get an extensive explanation about why.

To show a trivial example:

scope do
  let(:three) { 3 }
  spec "Printing Failing Specs" do
    one = 2
    two = 2
    @one_plus_two_plus_three = one + two + three
    @res = 3
    
    @one_plus_two_plus_three.to_i == @res
  end
end

It fails and the output will be

F

### Messages ###

[FAILING] Printing Failing Specs
Location:
  spec/matest_specs/printing_assertion_spec.rb:3:
Assertion: 
  @one_plus_two_plus_three.to_i == @res
Variables: 
  @one_plus_two_plus_three: 7
  @res: 3
Lets: 
  three: 3
Explanation:
  "@one_plus_two_plus_three.to_i == @res" =>
    false
  "@one_plus_two_plus_three.to_i" =>
    7

Matchers

Matest doesn't come with predefined matchers, it doesn't need them. In fact, the concept of a matcher is not required, because of the natural assertions nature of the library.

But you can define helper methods to assert long, complex or repeated logic:

def is_even?(val)
  val % 2 == 0
end

scope do
  spec do
    is_even?(4)
  end

  spec do
    ! is_even?(5)
  end
end

Aliases

You may be used to other keywords provenient from different testing frameworks. Matest has a couple of alias that you may use indistinctly to fit your style.

scope has the following aliases:

context (and xcontext)
describe (and xdescribe)
group (and xgroup)

spec has the following aliases:

it (and xit)
test (and xtest)
example (and xexample)

Configuration

You can add some configuration to the way the tests are run, by using the Matest.configure method.

To use it, you need to pass a block with the configuration instructions inside.

Matest.configure do |config|
  config.use_color
end

Color

You can tell Matest to use colored output by calling the use_color method on the config object

Matest.configure do |config|
  config.use_color
end

TODO ... or not TODO

Before and after callbacks
matest-given-ish
Allow seamless transition (separated gems)
- matest-assert (to move from TestUnit, Minitest::Unit, Cutest)
- matest-should (to move from RSpec
- matest-must (to move from Minitest::Spec)
Run ":" Should run the enclosing test or scope

Installation

Add this line to your application's Gemfile:

gem 'matest'

And then execute:

$ bundle

Or install it yourself as:

$ gem install matest

Known Issues

If the test contains a here doc and it fails, it raises a Sorcerer error

Contributing

Fork it ( https://github.com/[my-github-username]/matest/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

megatux/matest