From 1fcfc9c5c743414f681d8ec90a01ab91866fde8c Mon Sep 17 00:00:00 2001
From: "Tyler A. Young" <tyler@tylerayoung.com>
Date: Tue, 7 May 2024 10:47:12 -0500
Subject: [PATCH] Make Query.text/2 docs also point to assert_text/{2,3} (#770)

* Make Query.text/2 docs also point to assert_has_text/{2,3}

This beefs up the docs on `Query.text/2`, which a lot of examples combine with `assert_has/2` for asserting that a particular element has some text. Pointing to `assert_has_text/{2,3}` from the docs here would have resolved a recent issue Mitch kindly helped me with [in Slack](https://elixir-lang.slack.com/archives/C4H1XRC0J/p1715093283885629) where I was trying to assert on the text of multiple nested elements.

* Fix typo in function name
---
 lib/wallaby/query.ex | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/lib/wallaby/query.ex b/lib/wallaby/query.ex
index a93baefe..ed31f89d 100644
--- a/lib/wallaby/query.ex
+++ b/lib/wallaby/query.ex
@@ -170,7 +170,14 @@ defmodule Wallaby.Query do
   The second is by providing an existing query and a value to set as the `text`
   option.
 
-  ## Example
+  Note that the text you're querying for must appear in a single element.
+  To assert on text that appears in multiple (potentially nested) elements,
+  rather than using `assert_has/2` in combination with `Query.text/2`, use
+  `assert_text/{2,3}` directly.
+
+  ## Examples
+
+  ### Querying the text of a specific element
 
     ```
     submit_button = Query.css("#submit-button")
@@ -178,6 +185,34 @@ defmodule Wallaby.Query do
     update_button = submit_button |> Query.text("Update")
     create_button = submit_button |> Query.text("Create")
     ```
+
+  ### Asserting on the text of a single element
+
+      ```
+      submit_button = Query.css("#submit-button")
+      assert_has(session, Query.text(submit_button, "Create"))
+      ```
+
+  ### Asserting on the text of nested elements
+
+  HTML:
+
+      ```
+      <div id="unread-notifications">
+        Unread messages:
+        <strong>1 message</strong>
+      </div>
+      ```
+
+  Test:
+
+      ```
+      assert_text(session, "Unread messages: 1 message")
+
+      notifications_block = Query.css("#unread-notifications")
+      # It would *not* work to query as: Query.text(notifications_block, "Unread messages: 1 message")
+      assert_has(session, Query.text(notifications_block, "Unread messages:"))
+      ```
   """
   def text(query_or_selector, value_or_opts \\ [])