Pavlov

A BDD framework for your Elixir projects. It's main goal is to provide a rich, expressive syntax for you to develop your unit tests against. Think of it as RSpec's little Elixir-loving brother.

Pavlov is an abstraction built on top of the excellent ExUnit, Elixir's standard testing library, so all of its standard features are still supported.

Here's a short and sweet example of Pavlov in action:

defmodule OrderSpec do
  use Pavlov.Case, async: true
  import Pavlov.Syntax.Expect

  describe ".sum" do
    context "When the Order has items" do
      let :order do
        %Order{items: [
          {"burger", 10.0}
          {"fries", 5.2}
        ]}
      end
  it "sums the prices of its items" do
    expect Order.sum(order) |> to_eq 15.2
  end
end
  end
end

Table Of Contents

• Usage
• Describe and Context
• Let
• Subject
• Expects syntax
• Included Matchers
• Callbacks
  • before(:each)
  • before(:all)
• Mocking
  • Mocks with arguments
• Skipping tests
  • xit
  • xdescribe/xcontext
• Development
  • Running the tests
  • Building the docs
• Contributing

Usage

Add Pavlov as a dependency in your

mix.exs

defp deps do
  [{:pavlov, ">= 0.1.0", only: :test}]
end

After you are done, run

mix deps.get

Pavlov.start

Afterwards, running

mix test

Describe and Context

You may use the

describe

context

context

describe

contexts

described

Let

You can use

let

let :order do
  %Order{items: [
    {"burger", 10.0}
    {"fries", 5.2}
  ]}
end

Subject

You can use

subject

describe "Array" do
  subject do
    [1, 2, 3]
  end

  it "has the prescribed elements" do
    assert subject == [1, 2, 3]
  end
  context "Inner context" do
    it "can use an outer-scope subject" do
      assert subject == [1, 2, 3]
    end
  end
end

If you are using Expects syntax together with

subject

is_expected

describe "Numbers" do
  subject do: 5

  context "straight up, no message" do
    it is_expected |> to_eq 5
  end
  context "you can also use a custom message" do
    it "is equal to 5" do
      is_expected |> to_eq 5
    end
  end
end

By default, every created context via

describe

context

subject

nil

Expects syntax

You may use the regular ExUnit

assert

expect

If you wish to use this syntax, simply import the

Pavlov.Syntax.Expect

defmodule MyTest do
  use Pavlov.Case, async: true
  import Pavlov.Syntax.Expect
  #...
end

All core matchers are supported under both syntaxes.

Included Matchers

When using the

expects

elixir
expect 1 |> not_to_eq 2
expect(1 > 5) |> not_to_be_true

Visit the Pavlov Wiki to learn more about all of the core matchers available for your tests.

Callbacks

For now, Pavlov only supports callbacks that run before test cases. ExUnit's

on_exit

before

before(:each)

Runs the specified code before every test case.

describe "before :each" do
  before :each do
    IO.puts "A test is about to start"
    :ok
  end

  it "does something" do
    #...
  end
  it "does something else" do
    #...
  end
end

In this case,

"A test is about to start"

before(:all)

Runs the specified code once before any tests run.

describe "before :all" do
  before :all do
    IO.puts "This suite is about to run"
    :ok
  end

  it "does something" do
    #...
  end
  it "does something else" do
    #...
  end
end

In this case,

"This suite is about to run"

Mocking

Pavlov provides facilities to mock functions in your Elixir modules. This is achieved using Meck, an erlang mocking tool.

Here's a simple example using HTTPotion:

before :each do
  allow HTTPotion |> to_receive(get: fn(url) -> "" end)
end

it "gets a page" do
  result = HTTPotion.get("http://example.com")
  expect HTTPotion |> to_have_received :get
  expect result |> to_eq ""
end

If you want the mock to retain all other functions in the original module, then you will need to pass the

opts

List

allow

:passthrough

allow

opts

List

:no_link

List

before :each do
  allow(HTTPotion, [:no_link, :passthrough]) |> to_receive(get: fn(url) -> "" end)
end

Expectations on mocks also work using

asserts

called

before :each do
  allow HTTPotion |> to_receive(get: fn(url) -> "" end)
end

it "gets a page" do
  HTTPotion.get("http://example.com")
  assert called HTTPotion.get
end

Mocks with arguments

You can also perform assertions on what arguments were passed to a mocked method:

before :each do
  allow HTTPotion |> to_receive(get: fn(url) -> "" end)
end

it "gets a page" do
  HTTPotion.get("http://example.com")
  expect HTTPotion |> to_have_received :get |> with_args "http://example.com"
end

In

asserts

before :each do
  allow HTTPotion |> to_receive (get: fn(url) -> url end )
end

it "gets a page" do
  HTTPotion.get("http://example.com")
  assert called HTTPotion.get("http://example.com")
end

Skipping tests

Pavlov runs with the

--exclude pending:true

:pending

Pavlov offers several convenience methods to skip your tests, BDD style:

xit

Marks a specific test as pending and will not run it.

xit "does not run" do
  # This will never run
end

xdescribe/xcontext

Marks a group of tests as pending and will not run them. Just as

describe

context

xdescribe

xcontext

xdescribe "A pending group" do
  it "does not run" do
    # This will never run
  end

  it "does not run either" do
    # This will never run either
  end
end

Development

After cloning the repo, make sure to download all dependencies using

mix deps.get

Running the tests

Simply run

mix test

Building the docs

Run

MIX_ENV=docs mix docs

docs

Contributing

1. Fork it ( https://github.com/sproutapp/pavlov/fork )
2. Create your feature branch (

   git checkout -b my-new-feature

   )
3. Commit your changes (

   git commit -am 'Add some feature'

   )
4. Push to the branch (

   git push origin my-new-feature

   )
5. Create a new Pull Request