ESpec: Behaviour driven development framework for Erlang
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status

Behaviour driven development for Erlang.


ESpec is a behaviour driven development framework for Erlang. If you've ever used RSpec you'll feel at home, as this is basically the same.

It provides a structure for writing executable examples for how your code should behave. It uses the words "describe" and "it" so we can express concepts like a conversation:

"Describe an order."
"It sums the prices of its line items."

Basic Structure

describe("#generate_headers", fun() ->
    it("should generate Host and User-Agent headers", fun() ->
            {"Host", ""},
            {"User-Agent", "Twerl"}
        ] = stream_client_util:generate_headers()

The describe function is used to express a entity, for example a module or function, in your system whose behaviour you want to define. The body of this contain it functions which are used to express the behaviour.

Pending tests

it functions do not need a body, in this case they are called 'pending'. This means you can write out the high level behaviour, and later define it in more detail.

describe("#connect", fun() ->
    it("should return http errors"),

    it("should use http post method"),

    it("should use the correct url")


describe functions can be nested, to help you better isolate tests of different parts of the system.

describe("http client", fun() ->
    describe("when connected", fun() ->
        it("should pass data to the callback"),

        it("should return ok and the pid when the stream terminates")

    describe("when not connected", fun() ->
        it("should return an error when trying to make a request")


When describing different conditions for similar functionality of an entity you will find that there is a lot of repeated setup and tear down code, for example mocking. You can use filters which let you repeat code for each example:

describe("connection handler", fun() ->
    before_each(fun() ->
        catch meck:new(httpc, [unstick]),
        catch meck:new(stream_client, [passthrough])

    after_each(fun() ->
        ?assertEqual(true, meck:validate(httpc)),
        ?assertEqual(true, meck:validate(stream_client)),

    it("should have the client passed when connected")

The filters you can use are:

  • before_each - Run before each example
  • after_each - Run after each example
  • before_all - Run before all examples
  • after_all - Run after all examples


We also support assertions, you can use them as follows:

it("should treat the test as succeeded", fun() ->
      State = espec:run_spec(after_each_handling_spec, after_each_handling_spec(), espec_null_listener:new(), espec_null_listener),
      ?assertEqual([should_do_stuff, after_each], get(after_each_handling_spec)),
      ?assertMatch({error, {throw, something_went_wwwwrong, _}}, proplists:get_value("should do stuff", State))

Rather than printing out a badmatch error when something goes wrong, we should you the expression, what was expected and the result:

error handling spec
  after each filter errors
    should treat the test as failed if an after each fails (FAILED):
      assertMatch (line 67) failed
          proplists : get_value ( "should do stuff" , State )
      Expected To Match:
          { error , { throw , something_went_wwwwrong , _ } }

The supported assertions are as follows. These are compatible with those in EUnit.

  • ?assertEqual(Expected, Expression) - Ensure that Expression is equal to Expected.
  • ?assertMatch(Guard, Expression) - Ensure that Expression matches Guard.

Configuration Variables

Espec supports configuration variables like rspec instance variables. These are meant to be set during the before filters and accessed in the examples or in the after filters. The syntax is:

describe("instance variables", fun() ->
  before_each(fun() ->
    spec_set(var1, "variable 1")

  it("should do stuff", fun() ->

  after_each(fun() ->

If you modify an instance variable in an example the effects won't be seen in other examples. If you modify an instance variable in a nested group the effects won't be seen in the outer scope. 'Before all' methods run before all 'before each' methods so they can't see the effects of 'before each' methods. 'After all' methods will only be able to see the effects of 'before all' methods and won't see effects from examples, 'before each' methods, or 'after each' methods.

The espec command

The espec executable runs spec files and provides pretty output from the test results. You can pass it files or directories through which it will recursively look for spec files.

$ espec spec
http client
  when connected
    should pass data to the callback
    should return ok and the pid when the stream terminates (PENDING)
  when not connected
    should return an error when trying to make a request (FAILED):
      error {badmatch, false}

To build it yourself, clone the repository and run make generate. The binary bin/espec is self contained, so you can use it in other projects.

Getting started / Installation

The espec executable is self contained. Just copy it into the root of your project, just like you would rebar. You don't need to / can't install ESpec as a rebar dependency.

Create a directory called spec, and start creating spec files in there. For an example project using ESpec, take a look at Twerl.


Start an Erlang shell with reloader support:

make dev

Compile new code:

make compile

Run specs:

make spec


  • Fork the project.
  • Make your feature, addition or bug fix.
  • Add specs.
  • Send me a pull request.


MIT License. See for details.