Fluffy.Locator (Fluffy v0.7.0)

Copy Markdown View Source

A lazy, driver-independent element query.

Role locators accept these options:

  • :name (String.t/0) - Restrict the role locator by accessible name.

  • :exact (boolean/0) - Require an exact, case-sensitive accessible-name match.

Text, label, placeholder, alternative-text, and title locators accept:

  • :exact (boolean/0) - Require an exact, case-sensitive match.

Test-id locators accept:

  • :attribute (String.t/0) - Attribute used as the test-id source. The default value is "data-testid".

filter/2 accepts:

  • :visible (boolean/0) - Filter by structural visibility in Static/Live and rendered visibility in Playwright.

  • :exact (boolean/0) - Match the whole normalized text, case-sensitively, for has_text and has_not_text.

  • :has (struct of type Fluffy.Locator) - Keep elements containing a match for this locator.

  • :has_text (String.t/0) - Keep elements containing this normalized text.

  • :has_not (struct of type Fluffy.Locator) - Keep elements containing no match for this locator.

  • :has_not_text (String.t/0) - Keep elements that do not contain this normalized text.

Summary

Types

exact_option()
filter_option()
role_option()
scope()
t()
test_id_option()

Functions

and_(left, right)

Matches only elements matched by both locators, preserving the left locator's order.

append(locator, operation)
by_alt_text(text, options \\ [])
by_alt_text(parent, text, options)
by_css(css)
by_css(parent, css)
by_label(text, options \\ [])
by_label(parent, text, options)
by_placeholder(text, options \\ [])
by_placeholder(parent, text, options)
by_role(role, options \\ [])
by_role(parent, role, options)
by_test_id(test_id, options \\ [])
by_test_id(parent, test_id, options)
by_text(text, options \\ [])
by_text(parent, text, options)
by_title(text, options \\ [])
by_title(parent, text, options)
content_frame(owner)

Converts an iframe element query to a lazy query of its content frame.

describe(locator)
filter(locator, options)
first(locator)
frame_locator(css)

Creates a lazy frame scope. Frame traversal requires the Playwright driver.

frame_locator(parent, css)

Creates a nested frame scope relative to an element or frame query.

last(locator)
new(operation)
nth(locator, index)
or_(left, right)

Matches elements in either locator, once each in document order, retaining action strictness.

Types

exact_option()

@type exact_option() :: {:exact, boolean()}

filter_option()

@type filter_option() ::
  {:visible, boolean()}
  | {:exact, boolean()}
  | {:has, t()}
  | {:has_text, binary()}
  | {:has_not, t()}
  | {:has_not_text, binary()}

role_option()

@type role_option() :: {:name, binary()} | {:exact, boolean()}

scope()

@type scope() :: t() | Fluffy.FrameLocator.t()

t()

@type t() :: %Fluffy.Locator{operations: [term()]}

test_id_option()

@type test_id_option() :: {:attribute, binary()}

Functions

and_(left, right)

@spec and_(t(), t()) :: t()

Matches only elements matched by both locators, preserving the left locator's order.

The right locator resolves from the same query root, not within each left match. Inside filter/2's :has or :has_not, that root is the filter candidate.

by_css("#email") |> and_(by_label("Email", exact: true))

With Playwright, the right locator may be relative to the left locator's frame or use the same frame prefix. Playwright validates frame compatibility when the locator resolves; intersections across different frames are unsupported.

frame = frame_locator("#checkout")
by_css(frame, "input") |> and_(by_label(frame, "Email"))

Like other locators, intersections are lazy and retain normal action strictness.

append(locator, operation)

by_alt_text(text, options \\ [])

@spec by_alt_text(String.t(), [exact_option()]) :: t()
@spec by_alt_text(scope(), String.t()) :: t()

by_alt_text(parent, text, options)

@spec by_alt_text(scope(), String.t(), [exact_option()]) :: t()

by_css(css)

@spec by_css(String.t()) :: t()

by_css(parent, css)

@spec by_css(scope(), String.t()) :: t()

by_label(text, options \\ [])

@spec by_label(String.t(), [exact_option()]) :: t()
@spec by_label(scope(), String.t()) :: t()

by_label(parent, text, options)

@spec by_label(scope(), String.t(), [exact_option()]) :: t()

by_placeholder(text, options \\ [])

@spec by_placeholder(String.t(), [exact_option()]) :: t()
@spec by_placeholder(scope(), String.t()) :: t()

by_placeholder(parent, text, options)

@spec by_placeholder(scope(), String.t(), [exact_option()]) :: t()

by_role(role, options \\ [])

@spec by_role(atom(), [role_option()]) :: t()
@spec by_role(scope(), atom()) :: t()

by_role(parent, role, options)

@spec by_role(scope(), atom(), [role_option()]) :: t()

by_test_id(test_id, options \\ [])

@spec by_test_id(String.t(), [test_id_option()]) :: t()
@spec by_test_id(scope(), String.t()) :: t()

by_test_id(parent, test_id, options)

@spec by_test_id(scope(), String.t(), [test_id_option()]) :: t()

by_text(text, options \\ [])

@spec by_text(String.t(), [exact_option()]) :: t()
@spec by_text(scope(), String.t()) :: t()

by_text(parent, text, options)

@spec by_text(scope(), String.t(), [exact_option()]) :: t()

by_title(text, options \\ [])

@spec by_title(String.t(), [exact_option()]) :: t()
@spec by_title(scope(), String.t()) :: t()

by_title(parent, text, options)

@spec by_title(scope(), String.t(), [exact_option()]) :: t()

content_frame(owner)

(Playwright only) 
@spec content_frame(t()) :: Fluffy.FrameLocator.t()

Converts an iframe element query to a lazy query of its content frame.

describe(locator)

filter(locator, options)

@spec filter(t(), [filter_option()]) :: t()

first(locator)

frame_locator(css)

(Playwright only) 
@spec frame_locator(String.t()) :: Fluffy.FrameLocator.t()

Creates a lazy frame scope. Frame traversal requires the Playwright driver.

frame_locator(parent, css)

(Playwright only) 
@spec frame_locator(scope(), String.t()) :: Fluffy.FrameLocator.t()

Creates a nested frame scope relative to an element or frame query.

last(locator)

new(operation)

nth(locator, index)

or_(left, right)

@spec or_(t(), t()) :: t()

Matches elements in either locator, once each in document order, retaining action strictness.