ShouldI
=======

ExUnit is fine for small, simple applications, but when you want to do more complex test cases, it has limitations. ShouldI provides nested contexts to eliminate duplication in tests, and has better support for naming tests based on behavior. This API is based on the shoulda framework for Ruby on Rails. 

Installation
------------
Just add the hex dependency and add 

~~~
...
use ShouldI 
...
~~~

to your test script in place of 

~~~
...
use ExUnit.Case
...
~~~

Better Names
------------
When you're testing behavior, you can get better names with a more descriptive macro. The test code...

~~~
  test "should return ok on parse" do  
    assert :ok == Parser.parse
  end
~~~

...can become more descriptive and shorter with...


~~~
  should "return :ok on parse" do
     assert :ok == Parser.parse
  end
~~~

That's not all. Often test cases in functional languges can have too much repetition. We can eliminte much of that. 

Nested Contexts
---------------

Say you have a test case that needs some setup. ExUnit has support for a context that can be set once, and passed to all clients. You can use the `setup` method to pass a map to each of your test cases, like this:

~~~
defmodule MyFlatTest do
  setup context do
    {:ok, Dict.put context, :necessary_key, :neccessary_value}
  end
  
  test( "this test needs :necessary_key", context ) do
    assert context.necessary_key == :necessary_value
  end
end
~~~

This approach breaks down when several, but not all, tests need the same set of values. ShouldI solves this problem with nested contexts, which you can provide with the `with` keyword, like this:

~~~
defmodule MyFatTest do

  with "necessary_key" do
    setup context do
    {:ok, Dict.put context, :necessary_key, :neccessary_value}
    end
  
    should( "have necessary key", context ) do
      assert context.necessary_key == :necessary_value
    end
  
  with "sometimes_necessary_key" do
    setup context do
    {:ok, Dict.put context, :sometimes_necessary_key, :sometimes_neccessary_value}
    end
  
    should( "have necessary key", context ) do
      assert context.sometimes_necessary_key == :sometimes_necessary_value
    end
  end
end
~~~

This approach is much nicer than the alternatives when you're testing something like a controller with dramatically different requirements across tests:

~~~
  with "a logged in user" do
    setup context do
      login context, user
    end
    ...
  end
  
  with "a logged out user" do
     
     ...
     
  end
  
  with "a logged in admin" do
    setup context do
      login context, admin
    end
    ...
  end
  
~~~

Finally, you can package macros that write your own tests. Matchers encode common assertion patterns. For example, our plug matchers 

~~~
  with "a logged in admin" do
    setup context do
      login context, admin
    end
    with "a get to :index" do
      setup context do
        # process get
      end
      should respond_with :success
    end
  end
  ~~~

Special thanks to ThoughtBot's shoulda, which formed the foundation for this approach.