Support aria-label and aria-labelledby in find_by_label/assertions (#319)

Allow form fields to be located by their accessible name provided via
`aria-label` or `aria-labelledby`, in addition to `<label>` elements.
When a field is reachable by both, the `<label>` match takes precedence.

Note that this works for `assertions`. It does not work for `click_link` or 
`click_button`.

Author: Wigny

lib/phoenix_test.ex

@@ -588,6 +588,13 @@ defmodule PhoenixTest do
   <label for="search" class="sr-only">Search</label>
   <input id="search" type="text" name="q" />
   ```
+
+  In addition to `<label>` elements, the label can also be the accessible name
+  provided by the input's `aria-label` or `aria-labelledby` attribute:
+
+  ```html
+  <input type="text" name="q" aria-label="Search" />
+  ```
   """
   def fill_in(session, label, opts) when is_binary(label) and is_list(opts) do
     opts = Keyword.validate!(opts, [:with, exact: true])
@@ -1367,7 +1374,11 @@ defmodule PhoenixTest do
     Pass `true` to look for a checked field, or `false` to look for an
     unchecked field.
 
-  - `label`: the label associated to the form field with `value`, `selected`, or `checked`
+  - `label`: the label associated to the form field with `value`, `selected`, or
+  `checked`. The association can be a `<label>` element (wrapping the field or
+  pointing to it via `for`/`id`), or an accessible name provided by the field's
+  `aria-label` or `aria-labelledby` attribute. Note: if a field is reachable by
+  both a `<label>` and an `aria-*` attribute, the `<label>` match takes precedence.
 
   - `exact`: by default `assert_has/3` will perform a substring match (e.g. `a
   =~ b`). That makes it easier to assert text within HTML elements that also
@@ -1506,7 +1517,11 @@ defmodule PhoenixTest do
     Pass `true` to look for a checked field or `false` to look for an
     unchecked field.
 
-  - `label`: the label associated to the form field with `value`, `selected`, or `checked`
+  - `label`: the label associated to the form field with `value`, `selected`, or
+  `checked`. The association can be a `<label>` element (wrapping the field or
+  pointing to it via `for`/`id`), or an accessible name provided by the field's
+  `aria-label` or `aria-labelledby` attribute. Note: if a field is reachable by
+  both a `<label>` and an `aria-*` attribute, the `<label>` match takes precedence.
 
   - `exact`: by default `refute_has/3` will perform a substring match (e.g. `a
   =~ b`). That makes it easier to refute text within HTML elements that also

lib/phoenix_test/query.ex

@@ -217,6 +217,13 @@ defmodule PhoenixTest.Query do
   def find_by_label(html, input_selectors, label, opts \\ [exact: true]) do
     input_selectors = List.wrap(input_selectors)
 
+    case find_by_label_element(html, input_selectors, label, opts) do
+      {:found, _element} = found -> found
+      not_found -> with :not_found <- find_by_aria(html, input_selectors, label, opts), do: not_found
+    end
+  end
+
+  defp find_by_label_element(html, input_selectors, label, opts) do
     case find_labels(html, input_selectors, label, opts) do
       {:implicit_association, _label_element, element} ->
         {:found, element}
@@ -254,6 +261,62 @@ defmodule PhoenixTest.Query do
     end
   end
 
+  # Finds elements whose accessible name (via `aria-label` or `aria-labelledby`)
+  # matches `label`. Referenced `aria-labelledby` ids are resolved document-wide.
+  defp find_by_aria(html, input_selectors, label, opts) do
+    parsed = Html.parse_fragment(html)
+
+    input_selectors
+    |> Enum.flat_map(fn selector ->
+      parsed
+      |> Html.all(selector)
+      |> Enum.filter(&aria_name_match?(parsed, &1, label, opts))
+    end)
+    |> case do
+      [] -> :not_found
+      [element] -> {:found, element}
+      [_first | _rest] = found -> {:not_found, :found_many_labels_with_inputs, [], found}
+    end
+  end
+
+  defp aria_name_match?(parsed, element, label, opts) do
+    aria_label_match?(element, label, opts) or aria_labelledby_match?(parsed, element, label, opts)
+  end
+
+  defp aria_label_match?(element, label, opts) do
+    case Html.attribute(element, "aria-label") do
+      nil -> false
+      value -> text_match?(normalize_whitespace(value), label, opts)
+    end
+  end
+
+  defp aria_labelledby_match?(parsed, element, label, opts) do
+    case Html.attribute(element, "aria-labelledby") do
+      nil ->
+        false
+
+      ids ->
+        text =
+          ids
+          |> String.split()
+          |> Enum.map_join(" ", &labelledby_text(parsed, &1))
+          |> normalize_whitespace()
+
+        text != "" and text_match?(text, label, opts)
+    end
+  end
+
+  defp labelledby_text(parsed, id) do
+    case parsed |> Html.all("[id='#{id}']") |> Enum.at(0) do
+      nil -> ""
+      element -> Html.element_text(element)
+    end
+  end
+
+  defp normalize_whitespace(string) do
+    string |> String.replace(~r/\s+/, " ") |> String.trim()
+  end
+
   defp find_labels(html, input_selectors, label, opts) do
     html
     |> find("label", label, opts)
@@ -472,25 +535,18 @@ defmodule PhoenixTest.Query do
   end
 
   defp filter_by_element_text(elements, text, opts) do
-    exact_match = Keyword.get(opts, :exact, false)
-
-    filter_fun =
-      if exact_match do
-        &(Html.element_text(&1) == text)
-      else
-        &(Html.element_text(&1) =~ text)
-      end
-
-    Enum.filter(elements, filter_fun)
+    Enum.filter(elements, &text_match?(Html.element_text(&1), text, opts))
   end
 
   defp find_first_by_element_text(elements, text, opts) do
-    exact_match = Keyword.get(opts, :exact, false)
+    Enum.find(elements, &text_match?(Html.element_text(&1), text, opts))
+  end
 
-    if exact_match do
-      Enum.find(elements, &(Html.element_text(&1) == text))
+  defp text_match?(subject, text, opts) do
+    if Keyword.get(opts, :exact, false) do
+      subject == text
     else
-      Enum.find(elements, &(Html.element_text(&1) =~ text))
+      subject =~ text
     end
   end
 

test/phoenix_test/assertions_test.exs

@@ -158,6 +158,37 @@ defmodule PhoenixTest.AssertionsTest do
       end
     end
 
+    test "assert by aria-label", %{conn: conn} do
+      conn
+      |> visit("/page/by_value")
+      |> assert_has("input", label: "Sword")
+      |> assert_has("input", label: "Sword", value: "Sting")
+    end
+
+    test "assert by aria-labelledby", %{conn: conn} do
+      conn
+      |> visit("/page/by_value")
+      |> assert_has("input", label: "Steed", value: "Shadowfax")
+    end
+
+    test "assert by aria-labelledby with multiple ids", %{conn: conn} do
+      conn
+      |> visit("/page/by_value")
+      |> assert_has("input", label: "Middle Earth", value: "Mordor")
+    end
+
+    test "assert select by aria-label and selected", %{conn: conn} do
+      conn
+      |> visit("/page/by_value")
+      |> assert_has("select", label: "Weapon", selected: "Bow")
+    end
+
+    test "assert checkbox by aria-label and checked", %{conn: conn} do
+      conn
+      |> visit("/page/by_value")
+      |> assert_has(".ranger", label: "Aragorn", checked: true)
+    end
+
     test "succeeds when select option was selected by an HTML selected attribute", %{conn: conn} do
       conn
       |> visit("/page/by_value")
@@ -874,6 +905,29 @@ defmodule PhoenixTest.AssertionsTest do
       end
     end
 
+    test "refute by aria label when it doesn't match", %{conn: conn} do
+      conn
+      |> visit("/page/by_value")
+      |> refute_has("input", label: "Sword", value: "Glamdring")
+      |> refute_has("input", label: "Bow of Galadriel")
+    end
+
+    test "refute by aria-label raises an error if found", %{conn: conn} do
+      assert_raise AssertionError, fn ->
+        conn
+        |> visit("/page/by_value")
+        |> refute_has("input", label: "Sword")
+      end
+    end
+
+    test "refute by aria-labelledby raises an error if found", %{conn: conn} do
+      assert_raise AssertionError, fn ->
+        conn
+        |> visit("/page/by_value")
+        |> refute_has("input", label: "Steed")
+      end
+    end
+
     test "can refute a select by unselected option", %{conn: conn} do
       conn
       |> visit("/page/by_value")

test/phoenix_test/query_test.exs

@@ -742,6 +742,82 @@ defmodule PhoenixTest.QueryTest do
 
       assert {"label", [{"for", "wrapped-notes"}], _} = Html.element(element)
     end
+
+    test "returns {:found, element} matching by aria-label" do
+      html = """
+      <input name="search" aria-label="Search" />
+      """
+
+      assert {:found, element} = Query.find_by_label(html, "input", "Search")
+      assert {"input", [{"name", "search"}, {"aria-label", "Search"}], []} = Html.element(element)
+    end
+
+    test "returns {:found, element} matching by aria-labelledby" do
+      html = """
+      <span id="search-label">Search</span>
+      <input name="search" aria-labelledby="search-label" />
+      """
+
+      assert {:found, element} = Query.find_by_label(html, "input", "Search")
+      assert {"input", [{"name", "search"}, {"aria-labelledby", "search-label"}], []} = Html.element(element)
+    end
+
+    test "returns {:found, element} matching by aria-labelledby with multiple ids" do
+      html = """
+      <span id="label-1">Middle</span>
+      <span id="label-2">Earth</span>
+      <input name="realm" aria-labelledby="label-1 label-2" />
+      """
+
+      assert {:found, element} = Query.find_by_label(html, "input", "Middle Earth")
+      assert {"input", [{"name", "realm"}, {"aria-labelledby", "label-1 label-2"}], []} = Html.element(element)
+    end
+
+    test "aria matching honors exact option" do
+      html = """
+      <input name="search" aria-label="Search the archives" />
+      """
+
+      assert {:found, _} = Query.find_by_label(html, "input", "Search", exact: false)
+      assert {:not_found, :no_label, _} = Query.find_by_label(html, "input", "Search", exact: true)
+    end
+
+    test "aria matching normalizes whitespace" do
+      html = """
+      <input name="search" aria-label="  Search   the archives  " />
+      """
+
+      assert {:found, _} = Query.find_by_label(html, "input", "Search the archives", exact: true)
+    end
+
+    test "prefers <label> association over aria-label" do
+      html = """
+      <label for="labelled">Search</label>
+      <input id="labelled" name="labelled" />
+      <input name="aria" aria-label="Search" />
+      """
+
+      assert {:found, element} = Query.find_by_label(html, "input", "Search")
+      assert {"input", [{"id", "labelled"}, {"name", "labelled"}], []} = Html.element(element)
+    end
+
+    test "returns original label failure when aria also misses" do
+      html = """
+      <input name="search" aria-label="Something else" />
+      """
+
+      assert {:not_found, :no_label, _} = Query.find_by_label(html, "input", "Search")
+    end
+
+    test "returns :found_many_labels_with_inputs when multiple elements match via aria" do
+      html = """
+      <input name="one" aria-label="Search" />
+      <input name="two" aria-label="Search" />
+      """
+
+      assert {:not_found, :found_many_labels_with_inputs, [], inputs} = Query.find_by_label(html, "input", "Search")
+      assert length(inputs) == 2
+    end
   end
 
   describe "find_ancestor!/3" do

test/support/web_app/page_view.ex

@@ -445,6 +445,29 @@ defmodule PhoenixTest.WebApp.PageView do
         Merry
       </label>
       <input id="merry-checkbox" class="user" type="checkbox" name="users[]" value="merry" checked />
+
+      <input type="text" name="sword" value="Sting" aria-label="Sword" />
+
+      <span id="steed-label">Steed</span>
+      <input type="text" name="steed" value="Shadowfax" aria-labelledby="steed-label" />
+
+      <span id="realm-label">Middle</span>
+      <span id="realm-label-2">Earth</span>
+      <input type="text" name="realm" value="Mordor" aria-labelledby="realm-label realm-label-2" />
+
+      <select aria-label="Weapon" name="weapon">
+        <option value="axe">Axe</option>
+        <option value="bow" selected>Bow</option>
+      </select>
+
+      <input
+        class="ranger"
+        type="checkbox"
+        name="rangers[]"
+        value="aragorn"
+        aria-label="Aragorn"
+        checked
+      />
     </form>
     """
   end