In this blog post, we’ll write a few acceptance tests for an expenses report listing page, where we’ll interact with the report and some form elements.

To make possible to interact with the elements on the page, we’ll need a web browser driver. Hound accepts chrome_driver, firefox, phantomjs and selenium. My choice is phantomjs because I want to use a headless browser (I don’t want the driver to open a browser during the execution of the test suite).

Setup

First we’ll need to add Hound into our dependencies, so add the following line in your mix.exs:

{:hound, "~> 0.8"}

Make sure it’ll start during the test suite runtime. To do this we’ll need to add Application.ensure_all_started(:hound) before ExUnit.start in our test helper:

Application.ensure_all_started(:hound)
ExUnit.start

We’ll be using phantomjs as our web driver. Make sure it’s properly installed and that you can start it with phantomjs --wd. To configure it, add this to the config.exs file:

config :hound, driver: "phantomjs"

Take a look at this doc from Hound resources to check if you’d like different configs.

We’ll also need to set the server config in our config/test.exsto true.

config :my_app, MyApp.Endpoint,
  http: [port: 4001]
  server: true

That should do it! Before writing our first test, let’s define an IntegrationCase module, similar to the ModelCase and ConnCase provided by Phoenix, which will include all functionality we need to write our integration tests. Create the test/support/integration_case.ex file and add the following content:

defmodule MyApp.IntegrationCase do
  use ExUnit.CaseTemplate

  using do
    quote do
      use Hound.Helpers

      import Ecto.Model
      import Ecto.Query, only: [from: 2]
      import MyApp.Router.Helpers

      alias MyApp.Repo

      # The default endpoint for testing
      @endpoint MyApp.Endpoint

      hound_session
    end
  end

  setup tags do
    unless tags[:async] do
      Ecto.Adapters.SQL.restart_test_transaction(MyApp.Repo, [])
    end

    :ok
  end
end

There are a few lines that are worth commenting:

• use Hound.Helpers will include the helpers necessary for us to interact with our interface (take a look at the docs and explore them a little, they’ll be very helpful);
• hound_session will make sure that Hound will start and closes its session during the test execution;
• import MyApp.Router.Helpers will include helpers so we can manipulate routes and URLs.

Exercise

Let’s test!

We’re testing a simple list of expenses from a city (that example was extracted from an app we have been working on, but its scope was reduced so we can follow the steps more easily).

Take a look at its template code:

<div>
  <%= form_for @conn, city_expense_path(@conn, :index, @city.id), [as: :q, method: :get], fn f -> %>
    <div>
      <label for="q_status">Status</label>
      <%=
        select f, :status, [{"Paid", "paid"}, {"Cancelled", "cancelled"}], prompt: "All" %>
    </div>

    <div>
      <label for="q_supplier">Supplier</label>
      <%= text_input f, :supplier %>
    </div>

    <%= submit "Submit" %>
  <% end %>
</div>

<table>
  <thead>
    <th>ID</th>
    <th>Status</th>
    <th>Supplier</th>
    <th>Value</th>
    <th>Date</th>
  </thead>
  <tbody>
    <%= for expense <- @expenses do %>
      <tr>
        <td><%= expense.id %></td>
        <td><%= expense.status %></td>
        <td><%= expense.supplier.name %></td>
        <td><%= expense.value %></td>
        <td><%= expense.date %></td>
      </tr>
    <% end %>
  </tbody>
</table>

We’ll need a new test file, let’s put it at test/integration/expenses_list_test.exs. To use Hound’s facilities, we’ll need to use the IntegrationCase module that we have previously created.

defmodule MyApp.ExpenseListTest do
  use MyApp.IntegrationCase

end

We’ll be using three private functions to help us making assertions and interacting with elements in our test file. The first one, expense_on_the_list, will check if a given expense, that is represented by the Ecto model called MyApp.Expense, is in there. The second function is just a helper for getting the expenses list and the third will help us interact with a select input within a form.

defmodule MyApp.ExpenseListTest do
  use MyApp.IntegrationCase

  # ...

  defp expense_on_the_list(expense, list) do
    list
    |> visible_text
    |> String.contains?(expense.id)
  end

  defp expense_list_items do
    find_element(:tag, "tbody")
    |> find_all_within_element(:tag, "tr")
  end

  defp select_status(form, status) do
    form
    |> find_within_element(:id, "q_status")
    |> input_into_field(status)
  end
end

To interact with an element, you’ll always need to find the element on the page and for this, you need to know Hound’s page helpers. I’ve noticed that we ended up using find_element and find_all_within_element most of the time to find the elements on the page or in a context (i.e inside a previously found element).

Since this test is about the City resource, we’ve created just this city and navigated to it directly on the setup, since this would be a requirement for all the tests in this file, and shared it with all the tests through the setup context.

setup do
  city = insert_city!(%{name: "Winterfell"})

  navigate_to("/cities/#{city.id}/expenses")

  {:ok, city: city}
end

Navigation is another important Hound module. It will help us go through our app easily and get info about the page, like the current_path() function that returns the path we’re navigating on that moment.

Now that we’re on the page, we’ll be interacting with the form, by finding elements that are within it and filling or selecting values on them.

test "filter by supplier", %{city: city} do
  supplier = insert_supplier!(%{name: "Ned Stark"})
  supplier_b = insert_supplier!(%{name: "Bell Tower Management"})
  expense = insert_expense!(%{supplier: supplier, city: city, status: "paid"})
  insert_expense!(%{supplier: supplier_b, city: city, status: "paid"})

  search_form = find_element(:tag, "form")
  search_form
  |> find_within_element(:id, "q_supplier")
  |> fill_field("Ned")

  submit_element(search_form)


  items = expense_list_items
  assert length(items) == 1
  assert expense_on_the_list(expense, items)
end

The module responsible for these tasks is Element. It has very useful functions, like fill_field we used above. All of its functions require an element.

In the previous example, the interactions with the form ended with submit_element, but if we need any other action on it after this, we would need to re-assign it (otherwise, we’ll get a ** (RuntimeError) Element does not exist in cache error), like in the following example:

test "filter by statuses", %{city: city} do
  supplier = insert_supplier!(%{name: "Jon Snow"})

  cancelled_expense = insert_expense!(%{supplier: supplier, city: city, status: "cancelled"})
  paid_expense = insert_expense!(%{supplier: supplier, city: city, status: "paid"})

  search_form = find_element(:tag, "form")
  select_status(search_form, "Cancelled")

  submit_element(search_form)

  items = expense_list_items
  assert length(items) == 1
  assert expense_on_the_list(cancelled_expense, items)

  search_form = find_element(:tag, "form")
  select_status(search_form, "Paid")
  submit_element(search_form)

  items = expense_list_items
  assert length(items) == 1
  assert expense_on_the_list(paid_expense, items)
end

Verify

Runtime

One of the things I’ve paid a lot of attention during this experience was the test suite runtime. As expected, it can get slow with acceptance tests. The original app is still really tiny and before adding the acceptance tests, the runtime was:

Finished in 0.6 seconds (0.5s on load, 0.1s on tests)
23 tests, 0 failures, 2 skipped

After including two tests (but with more interactions than the ones presented), it was noticeable the test suite became slower. It tripled the runtime.

Finished in 1.8 seconds (0.5s on load, 1.2s on tests)
25 tests, 0 failures, 2 skipped

This effect is actually expected. We know that acceptance tests are expensive and that they should be a small portion of your test pyramid

There are a few things that can make acceptance tests faster:

• Upcoming Ecto v2.0 will allow us to run tests that use database persistence asyncronously;

• In my experience Phantom.js considerably faster than the other options, I recommend you to go with it.

You will definitely need to write some acceptance tests, but give preference to controller tests in most scenarios and use acceptance tests for important flows of your app (take a look at the user journey concept, that can give you some good insights).

Web driver server execution

Currently, Hound doesn’t execute the browser automatically during tests. You’ll need to start it; otherwise, your tests will fail. There may be some workarounds to achieve it, if you’re on OS X, you can run Phantomjs as a service.

Teardown

I really enjoyed playing with Hound, and I found very simple to work with it. Also, I see it as a potential project if you’re considering contributing to an Open Source Project.

I hope this post was useful and gave you some ideas of how to write acceptance tests with Elixir and Phoenix. If you have any questions or suggestions, I’m all ears (or eyes).

Which tool have you recently found to be useful when writing tests in Elixir?

The post Writing Acceptance tests in Phoenix first appeared on Plataformatec Blog.

But wait, you might be thinking that we are not able to change browser headers while dealing with Selenium. Capybara has a nice API to define new drivers and Selenium allows us to define different profiles with custom configurations for each driver. Lets see how we can put all this together to handle that:

Capybara.register_driver :iphone do |app|
  require 'selenium/webdriver'
  profile = Selenium::WebDriver::Firefox::Profile.new
  profile['general.useragent.override'] = "iPhone"

  Capybara::Driver::Selenium.new(app, :profile => profile)
end

Yup, it’s that simple =). We are creating a new driver for Capybara called :iphone, that will use Selenium with Firefox, but with a different profile, overriding the user agent string. This way you can pretend to your application that you are accessing through a “real” iPhone, by giving the “iPhone” string as user agent. You could also configure an :android driver, for instance, by simply changing the user agent string.

So now, how do we make use of that new driver in our specs? Here comes a simple example:

scenario 'access phone information using a modal box', :driver => :iphone do
  visit root_path

  page.should have_no_css "#fancybox-wrap"
  page.should have_no_content "0800 123456"

  within("header") { click_link "Telefones úteis" }

  within("#fancybox-wrap") do
    page.should have_content "0800 123456"
  end
end

We are just passing the :driver => :iphone option to our scenario. Remember that the latest Capybara versions use RSpec metadata options and will apply the :driver option automatically, changing the current driver to our registered :iphone in this case. For more info please refer to Capybara’s README.

You are now able to configure different user agents based on your application requirements, and test it in a full stack way. How about you, do you have any quick hint on how to test different user agents using another driver? Let us know in the comments

Updates (04/04/2014)

We were told that if you’re using Selenium Webdriver version 2.41.0, the code above will raise an exception. In order to fix that problem, you just need to replace Capybara::Driver::Selenium.new by Capybara::Selenium::Driver.new. Thanks Michael Joseph for suggesting that update.

The post Configuring User Agents with Capybara + Selenium Webdriver first appeared on Plataformatec Blog.

However, it is not easy to do acceptance tests with Omniauth as it depends on external services to work. So what should we do? When I face a scenario like this, I split the acceptance test in two parts: one before the external service and one after the external service response.

Testing the first one is trivial: you only have to ensure there is an <a> tag with href equals to “/auth/facebook” (or “/auth/#{insert_your_provider_here}” if you use another one). We don’t test any of the redirects done by OmniAuth internals, because it is already tested in gem’s tests, so we go to the next step: testing the OmniAuth callback.

Testing OmniAuth callbacks is in general cumbersome but for OAuth2 providers it is a bit easier as it uses Faraday internally to connect to the provider. With Faraday, we can configure a test adapter and stub calls to return what we want.

The OmniAuth strategy provides an entry point to the Faraday connection, but we don’t have an access to the strategy directly, so we need to store it globally. For a Facebook strategy, we can achieve it as below whenever configuring Omniauth middleware:

module OmniAuth
  mattr_accessor :facebook_strategy
end

middleware.use OmniAuth::Strategies::Facebook, "APP_ID", "APP_SECRET" do |strategy|
  OmniAuth.facebook_strategy = strategy
end

Note you will need OmniAuth 0.2.0 (which currently is OmniAuth master) as previous versions don’t yield a block on initialization like above.

With access to the strategy, we do the acceptance test. First, we define the hashes we will return on the Faraday responses.

FACEBOOK_INFO = {
  :id =>; '12345',
  :link => 'http://facebook.com/plataformatec',
  :email => 'myemail@example.com',
  :first_name => 'Plataforma',
  :last_name => 'Tecnologia',
  :website => '/'
}

ACCESS_TOKEN = {
  :access_token => "nevergonnagiveyouup"
}

Now, we will define the stubs. OAuth2 strategies do two requests: one to retrieve the access token and another to retrieve the user information. In this example, let’s stub the Facebook requests and assign these stubs to a new connection.

stubs = Faraday::Adapter::Test::Stubs.new do |b|
  b.post('/oauth/access_token') { [200, {}, ACCESS_TOKEN.to_json] }
  b.get('/me?access_token=nevergonnagiveyouup') { [200, {}, FACEBOOK_INFO.to_json] }
end

OmniAuth.facebook_strategy.client.connection = Faraday::Connection.new do |builder|
  builder.adapter :test, stubs
end

For each provider the URLs may differ, so an idea is to do this on a TDD way (or you can browse through the OmniAuth source code and see the url that it requests):

1. Assign the Faraday fake connection without stubs.
2. Run your test
3. See the test to raise an exception like “No stubbed request for DESIRED_URL”.
4. Add the stubbed request with the response that you want.
5. Repeat this process until the test pass

This is what we do on acceptance tests with OmniAuth: testing before and after the access to the external services.

Another approach is to do only one test by short-circuiting the provider authentication URLs. To do that on a Rails application, you can store the provider URL on a method like “OmniAuth.facebook_url” and stub the method to return the callback URL on your test. If you happen to be using Devise, the upcoming 1.2 version does the short-circuiting automatically for you, as you can see in Devise integration tests.

What about you? How do you stub OmniAuth requests and responses on your applications?

The post Acceptance tests for OmniAuth first appeared on Plataformatec Blog.