Skip to content

Expectations

flaui.core.expectations.expect(element, timeout=DEFAULT_TIMEOUT_MS, interval=DEFAULT_INTERVAL_MS)

Create a fluent, auto-waiting assertion for element.

Parameters:

Name Type Description Default
element 'AutomationElement'

The element to assert on.

 required
timeout int

Default time to wait for each expectation, in milliseconds.

 DEFAULT_TIMEOUT_MS
interval int

Polling interval, in milliseconds.

 DEFAULT_INTERVAL_MS

Returns:

Type Description
ElementAssertions

An :class:ElementAssertions builder (use .not_ for negation).
Source code in flaui/core/expectations.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
def expect(
    element: "AutomationElement",
    timeout: int = DEFAULT_TIMEOUT_MS,
    interval: int = DEFAULT_INTERVAL_MS,
) -> ElementAssertions:
    """Create a fluent, auto-waiting assertion for ``element``.

    :param element: The element to assert on.
    :param timeout: Default time to wait for each expectation, in milliseconds.
    :param interval: Polling interval, in milliseconds.
    :return: An :class:`ElementAssertions` builder (use ``.not_`` for negation).
    """
    return ElementAssertions(element, timeout=timeout, interval=interval)

flaui.core.expectations.ElementAssertions(element, timeout=DEFAULT_TIMEOUT_MS, interval=DEFAULT_INTERVAL_MS, is_negated=False)

Fluent expectation builder for a single :class:AutomationElement.

Each to_* matcher polls until the condition holds (or, after :attr:not_, until it no longer holds) and raises :class:AssertionError on timeout. Create instances via :func:expect.

Initialise the assertion wrapper.

Parameters:

Name Type Description Default
element 'AutomationElement'

The element under assertion.

 required
timeout int

Maximum time to wait for the expectation, in milliseconds.

 DEFAULT_TIMEOUT_MS
interval int

Polling interval, in milliseconds.

 DEFAULT_INTERVAL_MS
is_negated bool

Whether matchers should assert the negated condition.

 False
Source code in flaui/core/expectations.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def __init__(
    self,
    element: "AutomationElement",
    timeout: int = DEFAULT_TIMEOUT_MS,
    interval: int = DEFAULT_INTERVAL_MS,
    is_negated: bool = False,
) -> None:
    """Initialise the assertion wrapper.

    :param element: The element under assertion.
    :param timeout: Maximum time to wait for the expectation, in milliseconds.
    :param interval: Polling interval, in milliseconds.
    :param is_negated: Whether matchers should assert the negated condition.
    """
    self._element = element
    self._timeout = timeout
    self._interval = interval
    self._is_negated = is_negated

not_ property

Return a negated view of these assertions.

Returns:

Type Description
'ElementAssertions'

A new :class:ElementAssertions whose matchers assert the opposite condition.

to_be_checked(timeout=None)

Assert the element's is_checked state is truthy.

Parameters:

Name Type Description Default
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
132
133
134
135
136
137
138
def to_be_checked(self, timeout: int | None = None) -> None:
    """Assert the element's ``is_checked`` state is truthy.

    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(lambda: _safe_bool(lambda: self._element.is_checked), "to be checked", timeout)

to_be_enabled(timeout=None)

Assert the element is enabled.

Parameters:

Name Type Description Default
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
116
117
118
119
120
121
122
def to_be_enabled(self, timeout: int | None = None) -> None:
    """Assert the element is enabled.

    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(lambda: _safe_bool(lambda: self._element.is_enabled), "to be enabled", timeout)

to_be_offscreen(timeout=None)

Assert the element is off-screen.

Parameters:

Name Type Description Default
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
124
125
126
127
128
129
130
def to_be_offscreen(self, timeout: int | None = None) -> None:
    """Assert the element is off-screen.

    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(lambda: _safe_bool(lambda: self._element.is_offscreen), "to be offscreen", timeout)

to_be_visible(timeout=None)

Assert the element is available and on-screen.

Parameters:

Name Type Description Default
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
104
105
106
107
108
109
110
111
112
113
114
def to_be_visible(self, timeout: int | None = None) -> None:
    """Assert the element is available and on-screen.

    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(
        lambda: _safe_bool(lambda: self._element.is_available) and not _safe_bool(lambda: self._element.is_offscreen),
        "to be visible",
        timeout,
    )

to_have_name(expected, timeout=None)

Assert the element's name equals expected.

Parameters:

Name Type Description Default
expected str

The expected name value.

 required
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
140
141
142
143
144
145
146
147
def to_have_name(self, expected: str, timeout: int | None = None) -> None:
    """Assert the element's ``name`` equals ``expected``.

    :param expected: The expected name value.
    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(lambda: _read(self._element, "name") == expected, f"to have name {expected!r}", timeout)

to_have_text(expected, timeout=None)

Assert the element's text equals expected.

Parameters:

Name Type Description Default
expected str

The expected text value.

 required
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
149
150
151
152
153
154
155
156
def to_have_text(self, expected: str, timeout: int | None = None) -> None:
    """Assert the element's ``text`` equals ``expected``.

    :param expected: The expected text value.
    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(lambda: _read(self._element, "text") == expected, f"to have text {expected!r}", timeout)

to_have_value(expected, timeout=None)

Assert the element's value equals expected.

Parameters:

Name Type Description Default
expected Any

The expected value.

 required
timeout int | None

Optional per-call timeout override, in milliseconds.

 None

Raises:

Type Description
AssertionError

If the expectation is not met within the timeout.
Source code in flaui/core/expectations.py 
158
159
160
161
162
163
164
165
def to_have_value(self, expected: Any, timeout: int | None = None) -> None:
    """Assert the element's ``value`` equals ``expected``.

    :param expected: The expected value.
    :param timeout: Optional per-call timeout override, in milliseconds.
    :raises AssertionError: If the expectation is not met within the timeout.
    """
    self._check(lambda: _read(self._element, "value") == expected, f"to have value {expected!r}", timeout)