A fast, expressive and concise unit-testing framework.
Add Gemcutter to your gem sources:
!!!plain
sudo gem sources -a http://gemcutter.org
Then, simply install the Riot gem like so:
!!!plain
sudo gem install riot
In contrast to other popular Ruby testing frameworks such as Test::Unit,
Shoulda and RSpec,
Riot does not run a setup
and teardown
sequence before and after each test. This speeds
up the test runs quite a bit, but also puts restrictions on how you write your tests. In
general, you should avoid mutating any objects under test.
In Riot, tests reside in contexts. Within these, a topic object is defined through a
setup
block. The actual assertions are then made with assert
.
context "An Array" do
setup { Array.new }
asserts("is empty") { topic.empty? }
end
As you can see, the setup block doesn't use any instance variables to save the object under
test -- rather, the return value of the block is used as the topic. This object can then
be accessed in the assertions using the topic
attribute.
Furthermore, assertions need only return a boolean; true
indicates a pass, while false
indicates a fail.
Contexts can also be nested; the setup
blocks are executed outside-in before.
context "An Array" do
setup { Array.new }
context "with one element" do
setup { topic << "foo" }
asserts("is not empty") { !topic.empty? }
asserts("returns the element on #first") { topic.first == "foo" }
end
end
Macros greatly simplify a lot of assertions by capturing common practises, e.g. comparing
some value using the ==
operator. They work by calling the macro method on the return
value of asserts
:
asserts("#first") { topic.first }.equals("foo")
Other macros are available; for a complete overview, see {Riot::AssertionMacro}.
A common pattern is to make assertions on the return value of some attribute or method
on the topic
-- to simplify this, we have provided an easy to use shorthand. Simply
give a Symbol as the first argument to asserts
and leave out the block.
asserts(:first).equals("foo")
If you're like me, you like to write a bunch of failing tests for a context and then make
them pass. This can easily be done by simply calling an asserts
or should
command with
no block returning the actual value.
asserts("something special")
should("do something special")
Both of the above tests will fail. You can use this similar to a should_eventually
. The
difference is that should_eventually
is not technically a failure and will therefore be
ignored in time by (based on my experience). The above two blocks will actually show up as
failures and should hopefully drive you to making them pass.
Riot can output the test results in several ways, the default being story reporting. With this reporter, the output looks like the following:
!!!plain
An Array
+ asserts is empty
An Array with one element
+ asserts is not empty
+ asserts returns the element on #first
3 passes, 0 failures, 0 errors in 0.000181 seconds
The various shorthands and macros are built in a way that ensures expressive and specific feedback, e.g. the assertion
asserts(:full_name).matches(/^\w+ \w+$/)
yields the output
!!!plain
+ asserts #full_name matches /^\w+ \w+$/
Rack applications can easily be tested using Riot::Rack, which integrates Rack::Test into Riot.
require 'riot'
require 'riot-rack'
context "HelloWorldApp" do
# Specify your app using the #app helper. If you don't specify
# one, Riot::Rack will recursively look for a config.ru file.
app(HelloWorldApp)
# You can use all the Rack::Test helpers in the setup blocks.
setup { get '/' }
# You can access the response directly.
asserts(:status).equals(200)
asserts(:body).equals("Hello, World!")
end
Riot is still in its infancy, so both the internal and external API may change radically.
That being said, we would love to hear any thoughts and ideas, and bug reports are always
welcome. We hang out in #riot
on irc.freenode.net
.
The code is hosted on GitHub, and can be fetched with Git by running:
!!!plain
git clone git://github.com/thumblemonks/riot.git
Riot is released under the MIT license. See {file:MIT-LICENSE}.