Adds function docs for get_by_text

Also clarifies types for get_by_text options map, marks get_by_text_selector as public-but-internal, and adds a commented out function head for get_by_text to accept a regex as a reminder. Co-authored-by: German Velasco <[email protected]>
mechanical-orchard · Aug 19, 2024 · 04b0b51 · 04b0b51
1 parent f204497
commit 04b0b51
Show file tree

Hide file tree

Showing 3 changed files with 37 additions and 3 deletions.
diff --git a/lib/playwright/frame.ex b/lib/playwright/frame.ex
@@ -445,7 +445,17 @@ defmodule Playwright.Frame do
   # @spec get_by_test_id(Frame.t(), binary(), options()) :: Playwright.Locator.t() | nil
   # def get_by_test_id(frame, text, options \\ %{})
 
-  @spec get_by_text(Frame.t(), binary(), options()) :: Playwright.Locator.t() | nil
+  @doc """
+  Allows locating elements that contain given text.
+
+  ## Arguments
+
+  | key/name   | type   |            | description |
+  | ---------- | ------ | ---------- | ----------- |
+  | `text`     | param  | `binary()` | Text to locate the element for. |
+  | `:exact`   | option | `boolean()`| Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace. |
+  """
+  @spec get_by_text(Frame.t(), binary(), %{optional(:exact) => boolean()}) :: Playwright.Locator.t() | nil
   def get_by_text(frame, text, options \\ %{}) do
     locator(frame, Locator.get_by_text_selector(text, options))
   end

diff --git a/lib/playwright/locator.ex b/lib/playwright/locator.ex
@@ -669,13 +669,27 @@ defmodule Playwright.Locator do
   # @spec get_by_test_id(Locator.t(), binary(), options()) :: Locator.t()
   # def get_by_test_id(locator, text, options \\ %{})
 
-  @spec get_by_text(Locator.t(), binary(), options()) :: Locator.t()
+  @doc """
+  Allows locating elements that contain given text.
+
+  ## Arguments
+
+  | key/name   | type   |            | description |
+  | ---------- | ------ | ---------- | ----------- |
+  | `text`     | param  | `binary()` | Text to locate the element for. |
+  | `:exact`   | option | `boolean()`| Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace. |
+  """
+  @spec get_by_text(Locator.t(), binary(), %{optional(:exact) => boolean()}) :: Locator.t()
   def get_by_text(locator, text, options \\ %{}) when is_binary(text) do
     locator
     |> Locator.locator(get_by_text_selector(text, options))
   end
 
+  # @spec get_by_text(Locator.t(), Regex.t(), %{optional(:exact) => boolean()}) :: Locator.t()
+  # def get_by_text(locator, text, options \\ %{}) when is_regex(text)
+
   # NOTE: this is a kind of helper; not ideally part of the API.
+  @doc false
   def get_by_text_selector(text, options) do
     exact = Map.get(options, :exact, false)
 

diff --git a/lib/playwright/page.ex b/lib/playwright/page.ex
@@ -414,7 +414,17 @@ defmodule Playwright.Page do
   # @spec get_by_test_id(Page.t(), binary(), options()) :: Playwright.Locator.t() | nil
   # def get_by_test_id(page, text, options \\ %{})
 
-  @spec get_by_text(Page.t(), binary(), options()) :: Playwright.Locator.t() | nil
+  @doc """
+  Allows locating elements that contain given text.
+
+  ## Arguments
+
+  | key/name   | type   |            | description |
+  | ---------- | ------ | ---------- | ----------- |
+  | `text`     | param  | `binary()` | Text to locate the element for. |
+  | `:exact`   | option | `boolean()`| Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace. |
+  """
+  @spec get_by_text(Page.t(), binary(), %{optional(:exact) => boolean()}) :: Playwright.Locator.t() | nil
   def get_by_text(page, text, options \\ %{}) do
     main_frame(page) |> Frame.get_by_text(text, options)
   end