Add PhoenixTest.within

We add a `within` helper to help us scope down filling out forms with
the new `fill_in`, `select`, etc. form helpers. Since they do not take a
CSS selector as their second argument (like most other helpers do),
having a `within` helper seems more necessary to scope forms.

Though it's possible the `within` helper works with other helpers (since
we're really changing the `render_html` to only render the scoped HTML),
we do not officially support it for all helpers.

lib/phoenix_test.ex

@@ -218,6 +218,9 @@ defmodule PhoenixTest do
   """
   defdelegate click_button(session, selector, text), to: Driver
 
+  @doc false
+  defdelegate within(session, selector, fun), to: Driver
+
   @doc false
   defdelegate fill_in(session, label, attrs), to: Driver
 

lib/phoenix_test/driver.ex

@@ -6,6 +6,7 @@ defprotocol PhoenixTest.Driver do
   def click_link(session, selector, text)
   def click_button(session, text)
   def click_button(session, selector, text)
+  def within(session, selector, fun)
   def fill_in(session, label, attrs)
   def select(session, option, attrs)
   def check(session, label)

lib/phoenix_test/live.ex

@@ -7,7 +7,7 @@ defmodule PhoenixTest.Live do
 
   alias PhoenixTest.ActiveForm
 
-  defstruct view: nil, conn: nil, active_form: ActiveForm.new()
+  defstruct view: nil, conn: nil, active_form: ActiveForm.new(), within: :none
 
   def build(conn) do
     {:ok, view, _html} = live(conn)
@@ -26,13 +26,23 @@ defimpl PhoenixTest.Driver, for: PhoenixTest.Live do
   alias PhoenixTest.Field
   alias PhoenixTest.Form
   alias PhoenixTest.Html
+  alias PhoenixTest.Query
 
   def render_page_title(%{view: view}) do
     page_title(view)
   end
 
-  def render_html(%{view: view}) do
-    render(view)
+  def render_html(%{view: view, within: within}) do
+    case within do
+      :none ->
+        render(view)
+
+      selector ->
+        view
+        |> render()
+        |> Query.find!(selector)
+        |> Html.raw()
+    end
   end
 
   def click_link(session, text) do
@@ -84,6 +94,13 @@ defimpl PhoenixTest.Driver, for: PhoenixTest.Live do
     end
   end
 
+  def within(session, selector, fun) do
+    session
+    |> Map.put(:within, selector)
+    |> fun.()
+    |> Map.put(:within, :none)
+  end
+
   def fill_in(session, label, with: value) do
     field =
       session

lib/phoenix_test/static.ex

@@ -3,7 +3,7 @@ defmodule PhoenixTest.Static do
 
   alias PhoenixTest.ActiveForm
 
-  defstruct conn: nil, active_form: ActiveForm.new()
+  defstruct conn: nil, active_form: ActiveForm.new(), within: :none
 
   def build(conn) do
     %__MODULE__{conn: conn}
@@ -33,9 +33,18 @@ defimpl PhoenixTest.Driver, for: PhoenixTest.Static do
     end
   end
 
-  def render_html(%{conn: conn}) do
-    conn
-    |> html_response(conn.status)
+  def render_html(%{conn: conn, within: within}) do
+    case within do
+      :none ->
+        conn
+        |> html_response(conn.status)
+
+      selector ->
+        conn
+        |> html_response(conn.status)
+        |> Query.find!(selector)
+        |> Html.raw()
+    end
   end
 
   def click_link(session, text) do
@@ -95,6 +104,13 @@ defimpl PhoenixTest.Driver, for: PhoenixTest.Static do
     end
   end
 
+  def within(session, selector, fun) do
+    session
+    |> Map.put(:within, selector)
+    |> fun.()
+    |> Map.put(:within, :none)
+  end
+
   def fill_in(session, label, with: value) do
     field =
       session

test/phoenix_test/live_test.exs

@@ -208,6 +208,38 @@ defmodule PhoenixTest.LiveTest do
     end
   end
 
+  describe "within/3" do
+    test "scopes assertions within selector", %{conn: conn} do
+      conn
+      |> visit("/live/index")
+      |> assert_has("button", text: "Reset")
+      |> within("#email-form", fn session ->
+        refute_has(session, "button", text: "Reset")
+      end)
+    end
+
+    test "scopes further form actions within a selector", %{conn: conn} do
+      conn
+      |> visit("/live/index")
+      |> within("#email-form", fn session ->
+        session
+        |> fill_in("Email", with: "[email protected]")
+      end)
+      |> assert_has(input(label: "Email", value: "[email protected]"))
+    end
+
+    test "raises when data is not in scoped HTML", %{conn: conn} do
+      assert_raise ArgumentError, ~r/Could not find element with label "User Name"/, fn ->
+        conn
+        |> visit("/live/index")
+        |> within("#email-form", fn session ->
+          session
+          |> fill_in("User Name", with: "Aragorn")
+        end)
+      end
+    end
+  end
+
   describe "fill_in/3" do
     test "fills in a single text field based on the label", %{conn: conn} do
       conn

test/phoenix_test/static_test.exs

@@ -284,6 +284,39 @@ defmodule PhoenixTest.StaticTest do
     end
   end
 
+  describe "within/3" do
+    test "scopes assertions within selector", %{conn: conn} do
+      conn
+      |> visit("/page/index")
+      |> assert_has("button", text: "Get record")
+      |> within("#email-form", fn session ->
+        refute_has(session, "button", text: "Get record")
+      end)
+    end
+
+    test "scopes further form actions within a selector", %{conn: conn} do
+      conn
+      |> visit("/page/index")
+      |> within("#email-form", fn session ->
+        session
+        |> fill_in("Email", with: "[email protected]")
+        |> click_button("Save Email")
+      end)
+      |> assert_has("#form-data", text: "email: [email protected]")
+    end
+
+    test "raises when data is not in scoped HTML", %{conn: conn} do
+      assert_raise ArgumentError, ~r/Could not find element with label "User Name"/, fn ->
+        conn
+        |> visit("/page/index")
+        |> within("#email-form", fn session ->
+          session
+          |> fill_in("User Name", with: "Aragorn")
+        end)
+      end
+    end
+  end
+
   describe "fill_in/3" do
     test "fills in a single text field based on the label", %{conn: conn} do
       conn