Skip to content

common_browser.contracts.targets

Immutable browser queries; a query is distinct from an observed node identity.

Classes

Target

Bases: BaseModel

Describe one element, with explicit nesting, frame and ordinal selection.

Queries may resolve again as a document changes. Use an ElementRef from a scan when an action must address the exact observed node instead.

Fields and properties declared here; inherited members belong to the bases above.

exact

exact: bool = True

frame

frame: Target | None = Field(default=None, repr=False)

index

index: int | None = Field(default=None, ge=0)

kind

kind: Literal['css', 'role', 'label', 'text', 'placeholder', 'test_id', 'title', 'alt']

name

name: str | TextPattern | None = Field(default=None, repr=False)

value

value: str | TextPattern = Field(repr=False)

within

within: Target | None = Field(default=None, repr=False)

alt

@classmethod
def alt(text: str | TextPattern | re.Pattern[str], *, exact: bool = True) -> Self

css

@classmethod
def css(selector: str) -> Self

in_frame

def in_frame(target: Target) -> Self

inside

def inside(target: Target) -> Self

label

@classmethod
def label(text: str | TextPattern | re.Pattern[str], *, exact: bool = True) -> Self

nth

def nth(index: int) -> Self

placeholder

@classmethod
def placeholder(text: str | TextPattern | re.Pattern[str], *, exact: bool = True) -> Self

role

@classmethod
def role(role: str, *, name: str | TextPattern | re.Pattern[str] | None = None, exact: bool = True) -> Self

test_id

@classmethod
def test_id(value: str) -> Self

text

@classmethod
def text(text: str | TextPattern | re.Pattern[str], *, exact: bool = True) -> Self

title

@classmethod
def title(text: str | TextPattern | re.Pattern[str], *, exact: bool = True) -> Self

TextPattern

Bases: BaseModel

A serialized text regex with explicit flags, using Playwright/JS syntax.

Python compilation catches invalid input, but does not translate Python-only regex constructs into JavaScript. Only the flags supported by Playwright are accepted; the pattern and flags retain separate identities in JSON.

Fields and properties declared here; inherited members belong to the bases above.

flags

flags: int = Field(default=0, ge=0, strict=True)

pattern

pattern: str = Field(repr=False)

compile

def compile() -> re.Pattern[str]