= Test::Unit Given

Author::  Dave Copeland (mailto:davetron5000 at g mail dot com)
Copyright:: Copyright (c) 2011 by Dave Copeland
License:: Distributes under the Apache License, see LICENSE.txt in the source distro

Get your Test::Unit test cases fluent, without RSpec, magic, or crazy meta-programming.

This gives you two simple tools to make your test cases readable:

* Given/When/Then to delineate which parts of your tests do what
* A method "test_that" that defines test cases with strings instead of method names (much like +test+ in Rails tests)

== Install

    gem install test_unit-given

== Example

    class Circle
      def initialize(radius)
        @radius = radius
      end

      def area
        @radius * @radius * 3.14
      end

    end

    require 'test/unit/given'

    class CircleTest < Test::Unit::Given::TestCase
      test_that {
        Given {
          @circle = Circle.new(10)
        }
        When {
          @area = @circle.area
        }
        Then {
          assert_equal 314,@area
        }
      }
    end

You can, of course, provide a description for your test if you need to:

    class CircleTest < Test::Unit::Given::TestCase
      test_that "the area is correctly calculated" do
        Given {
          @circle = Circle.new(10)
        }
        When {
          @area = @circle.area
        }
        Then {
          assert_equal 314,@area
        }
      end

If you don't want to extend our base class, you can mix in the features explicitly:

    require 'test/unit/given/simple'

    class CircleTest < Test::Unit::TestCase

      include Test::Unit::Given::Simple
      include Test::Unit::Given::TestThat

      test_that {
        Given {
          @circle = Circle.new(10)
        }
        When {
          @area = @circle.area
        }
        Then {
          assert_equal 314,@area
        }
      }
    end

You can also strictly enforce the use in your tests:

    require 'test/unit/given/strict'

    class CircleTest < Test::Unit::TestCase
      include Test::Unit::Given::Strict
      include Test::Unit::Given::TestThat

      test_that {
        @circle = Circle.new(10)
        When {
          # this causes an error, because there's no Given
          @area = @circle.area
        }
        Then {
          assert_equal 314,@area
        }
      }
    end

Finally, you can re-use blocks:

    class CircleTest < Test::Unit::Given::TestCase

      def circle_with_radius(r)
        @circle = Circle.new(r)
      end

      def get_area
        @area = @circle.area
      end

      def area_should_be(area)
        assert_equal area,@area
      end

      test_that {
        Given circle_with_radius(10)
        When get_radius
        Then area_should_be(314)
      }
    end

=== What about block-based assertions, like +assert_raises+

You can use the non-strict version like so:

    class CircleTest < Test::Unit::Given::TestCase

      test_that "there is no diameter method" do
        Given {
          @cicle = Circle.new(10)
        }
        Then {
          assert_raises NoMethodError do
            When {
              @cirlce.diameter
            }
          end
        }
      end
    end

This won't work in strict mode for now.

== WTF?  Why?

Just because you're using Test::Unit doesn't mean you can't write fluent, easy to understand tests.
You really don't need RSpec, and RSpec has some baggage, such as nonstandard assignment, confusing class_eval
blocks, and generally replaces stuff you can do in plain Ruby.  Here, everything is simple, plain Ruby.  No
magic, nothing to understand. 

If you like Test::Unit, and you want to make your tests a bit more readable, this is for you.