defactosoftware/test_selector

Elixir library to help selecting the right elements in your tests.

TestSelector

A set of Elixir helpers to set/get test selectors to/from elements in a Phoenix app (when Mix.env == :test). These selectors are hashed (scoped to the view module they are used in) for accurate selection and "leakage" prevention. See our Wiki for examples.

Why? Because we prefer reserving classes for styling, and id's have limitations because they have to be unique.

Dependencies

• Floki v0.25.x and higher

Installation

def deps do
  [
    {:test_selector, "~> 0.3.3"}
  ]
end

Use TestSelector.HTML.Helpers to your web.ex.

• In phoenix 1.2.0 at web/web.ex
• In newer Phoenix versions lib/your_project/web/web.ex

Add somewhere along:

def view(opts \\ []) do
  quote do
    ...
    use Phoenix.HTML

    use TestSelector.HTML.Helpers
    ...
  end
end

Testing with Floki

In the tests import the TestSelector.Test.FlokiHelpers:

defmodule Project.Web.MyTest do
  ...

  import TestSelector.Test.FlokiHelpers
  ...
end

Tests

Run the tests:

mix test

Copyright and License

Copyright (c) 2017 Defacto

Released under the MIT License, which can be found in the repository in LICENSE.md.

test_selector's Issues

Helpers for finding multiple test elements

find_test_element uses Hound Hound.Helpers.Page.find_element/3 to find a single element.

We should also cover other Hound helpers:

• find_all_test_elements > Hound.Helpers.Page.find_all_elements/3.
• find_within_test_element > Hound.Helpers.Page.find_within_element/4
• etc.

Add retries option to the search and find functions

Just like Hound's find_element/3 I'd like to add the retries option:

def find_test_element(view_module, retries \\ 5)
def search_test_element(view_module, retries \\ 5)

By default Hound retries 5 times. But when I want to make sure a page is lacking an element, I might want to check only once:

assert search_test_element(UserView, "does-not-exist", 1) == {:error, :no_such_element}

Multiple retries significantly increases the testing duration.

Looks like adding an optional attribute will conflict in our function arity, so need to find a workaround.

Extend the Hound `find_element` function

This would be nice:

def find_element(:test, view_module, retries \\ 5) do
  {:safe, test_selector} = view_module.test()
  find_element(:xpath, ~s|//*[@#{test_selector}]|, retries)
end

find_element(:test, MyModule)

But this :(

** (CompileError) lib/test_selector/test_helpers.ex:1: imported Hound.Helpers.Page.find_element/2 conflicts with local function

Add helpers and examples for usage with Floki

We should mention we're also supporting Floki out of the box:

html
|> Floki.find("[test-selector=#{SomeView.test_selector("user")}")
|> Floki.attribute("test-value")

{:safe, selector} = IndexView.test()
Floki.find(html, "[#{selector}]")

And we might want to rename TestSelector.Test.Helpers to TestSelector.Hound.Helpers, and optionally add TestSelector.Floki.Helpers (if any).

Option to disable output for all test helpers (e.g. in production)

This way we can output/use the helpers in development and test environments, but hide them in production.

Thoughts on this?

Make the README houndless

Since using test_selector can be done without, and is done without using hound, can we move the hound mentions to the Wiki and keep the README clean?