BareTest

Summary

A testframework that doesn’t stand in your way or forces you to learn a new language. Two methods is all that is required to know. If you need it, it provides you with all kinds of features to support you writing your tests.

Also See

Executable Docs

doc/baretest.rdoc

IRC

The channel #ruby-lang on irc.freenode.org

I’m there under the nick apeiros.

Beware, I’m idling there 24/7, so my nick being in there doesn’t mean I’m in front of the computer.

Description

Baretest is a Testframework that tries to stay out of your way, but support you when you want it. In order to do so it has a load of features:

  • Straightforward and terse assertions (just a block whose return value defines success/failure)

  • Easy grouping of assertions into suites

  • BDD style specifications/test descriptions (NOT code), also extractable

  • Uncomplicated dependency testing and skipping

  • Helpers to deal painlessly with raising, throwing, float imprecision, unordered collections etc.

  • Ships with colored Shell formatter, Diagnostic-, XML- and TAP formatter

  • Interactive mode - drops you into an irb session within failed assertion with all setup methods executed, so you can inspect interactively why it failed.

  • Trivial to add new formatters (the standard formatters are only roughly 20-50 lines of code each)

  • Teardown and Setup for suites

  • Callbacks to integrate mock libraries

  • API to use it from code, such as rake tasks (comes with an example rake-task)

  • baretest executable to run tests on multiple files at once

  • Diagnostic assertion helpers (e.g. same(:a, :b) will give you ‘Expected :a but got :b’ as diagnostic)

Quick Try

  1. Download from github and unpack (or clone)

  2. Change into the baretest directory: ‘cd the/baretest/directory`

  3. Run the examples: ‘./bin/baretest examples/test.rb`

That’s it. Alternatively you can run baretests own tests, and play with formatters: ‘./bin/baretest -f tap`

Install

  1. run ‘gem install baretest`, alternatively run `sudo gem install baretest`

  2. There is no 2.

To get baretest edge, use:

  1. Download from github and unpack (or clone)

  2. Change into the baretest directory: ‘cd the/baretest/directory`

  3. Run the installation task: ‘rake gem:install` (alternatively `rake install:lib`)

IMPORTANT: if the gem:install task fails, it might be because I forgot to update the MANIFEST.txt. Simply delete MANIFEST.txt, then run ‘rake manifest:create` and then retry `rake gem:install`. Also notice that you should have the gems ’nokogiri’ and ‘rdoc’ installed.

If you have multiple ruby versions installed parallely, this might pick the wrong gem executable to install the gem. You can set the GEM env variable to ensure it uses the right one: ‘rake gem:install GEM=gem1.9`

Executable

Usage:

baretest [command] [options] *(selector | -selector)
  command:   The command to run. See `baretest commands`
  options:   The flags and options, see in the "Options" section.
  selector:  The tests to run. Example:
               baretest -- test/suite/a -test/suite/a/x @tag -@other %failure -%pending
             Defaults to 'test/{suite,unit,integration,system}
             See `baretest selectors` to get more information

Default command is 'run', which runs the testsuite or the provided testfiles.

Options:

      --commands       overview over the commands
  -d, --debug          set debugging flags (set $DEBUG to true)
  -i, --interactive    drop into IRB on error or failure. Use 'help!' in the irb session for more information
  -f, --format FORMAT  use FORMAT for output, see `baretest formats`
  -s, --setup FILE     specify setup file
  -w, --warn           turn warnings on for your script
  -h, --help           help for usage and flags
  -v, --version        print the version and exit
      --init           Deprecated form for `baretest --init`

Options for 'CLI' formatter:

  -c, --[no-]color    Enable/disable output coloring
  -p, --[no-]profile  Enable/disable profiling assertions

Environment variables for 'CLI' formatter:

* COLOR    Enable/disable output coloring
* PROFILE  Enable/disable profiling assertions

Environment variables:

* FORMAT       use FORMAT for output, see `baretest formats`
* VERBOSE      turn warnings on for your script
* INTERACTIVE  drop into IRB on error or failure. Use 'help!' in the irb session for more information

A Bit of Background

Originally, baretest started out as a project for shits & giggles on the flight back from vegas (railsconf09), to prove that it is possible to have a fully fledged test-framework in under 100 lines of source-code. Later I realized that this project could become more. For one it was (still is) dead simple to add another formatter, it is just as dead simple to embedd it in code. The principles are trivial to understand, embrace and extend. Upon that it dawned me, that the project was viable and I began adding features not found in other projects.

Example Testsuite

From examples/test.rb:

BareTest.suite do
  # assertions and refutations can be grouped in suites. They will share
  # setup and teardown
  # they don't have to be in suites, though
  suite "Success" do
    assert "An assertion returning a trueish value (non nil/false) is a success" do
      true
    end
  end

  suite "Failure" do
    assert "An assertion returning a falsish value (nil/false) is a failure" do
      false
    end
  end

  suite "Pending" do
    assert "An assertion without a block is pending"
  end

  suite "Error" do
    assert "Uncaught exceptions in an assertion are an error" do
      raise "Error!"
    end
  end

  suite "Special assertions" do
    assert "Assert a block to raise" do
      raises do
        sleep(rand()/3+0.05)
        raise "If this raises then the assertion is a success"
      end
    end

    assert "Assert a float to be close to another" do
      a = 0.18 - 0.01
      b = 0.17
      within_delta a, b, 0.001
    end

    suite "Nested suite" do
      assert "Assert two randomly ordered arrays to contain the same values" do
        a = [*"A".."Z"] # an array with values from A to Z
        b = a.sort_by { rand }
        equal_unordered(a, b) # can be used with any Enumerable, uses hash-key identity
      end
    end
  end

  suite "Setup & Teardown" do
    setup do
      @foo = "foo"
      @bar = "bar"
    end

    assert "@foo should be set" do
      @foo == "foo"
    end

    suite "Nested suite" do
      setup do
        @bar = "inner bar"
        @baz = "baz"
      end

      assert "@foo is inherited" do
        @foo == "foo"
      end

      assert "@bar is overridden" do
        @bar == "inner bar"
      end

      assert "@baz is defined only for inner" do
        @baz == "baz"
      end
    end

    teardown do
      @foo = nil # not that it'd make much sense, just to demonstrate
    end
  end

  suite "Dependencies", :requires => ['foo', 'bar'] do
    assert "Will be skipped, due to unsatisfied dependencies" do
      failure "Why the heck do you have a 'foo/bar' file?"
    end
  end
end

Credits & Contributions

  • dominikh

    • adding mocha integration

    • showing me every dirty little bit I did wrong

    • fixes

    • added line number on failures

  • Tass

    • adding rr integration

    • reporting bugs

  • robgleeson

    • Introducing me to rack-test

    • Feedback

Known bugs

Currently none.

Known issues

  • A setup that raises an exception will cause all teardowns to not be executed. This will change in a future release as follows: a setup that raises an exception will only cause teardowns defined on the same suite not to be executed.

  • –interactive can’t be used to investigate problems in setup or teardown

  • Inherited skip reasons are not reported

Foot Notes

<sup>1</sup>

The abbreviated form without support code and output formatters. The normal code is expanded to more lines for readability.