Acceptance testing seems to be in its first steps in the Elixir ecosystem, but there are already some cool libs that can help us out to do it. I’m going to show you how we did it with Hound.

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:

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

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.

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.

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.

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:

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:

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?

15 responses to “Writing Acceptance tests in Phoenix”

Hey, I think this is a great post so thanks for sharing. Something that always bugs me when people do acceptance testing is the tight coupling of implementation to specification by explicit reference to dom elements such as `tbody` and `tr`. What happens if the UI changes to using divs instead? IMHO using dom data attributes or classes reduces the fragility somewhat, enabling the front end implementation to be changed without forcing the spec to change. Just MHO though, opinions may vary.

The code presented in the post is just an example for didact purpose. In a real-case scenario, we'd probably have a more complex DOM with style, so I’d use the same approach you mentioned.

Although, I don't really have a problem referencing elements on the tests when the template is simple like that. Even if it breaks my suite when the change happens, I actually like my test suite reacting to change.

Upon adding some IO.inspect statements in hound, I discovered that it needed a driver: “phantomjs” instead of the server option. After this change, it was running succesfully on my machine. Thank you for the article!

Interesting, but I’d prefer a more declarative way to define the acceptance tests. Maybe I’m too used to Cucumber for ATDD and BDD … but I’m thinking in write my tests in Cucumber with steps implementation in ruby or javascript (nodejs).

I have a good feeling that these tools will evolve nicely. A thing that makes me believe that is the possibility of running async test using database (with Ecto). I believe that this will have a good impact on our test performance.

I am running selenium server using a docker container. I get the message as selenium up and running in that terminal.
Then what might be the problem?? Please help. I cannot understand the error message