UIMatcher#

A lazy selector of views in all opened windows, with actions and checks to run on them.

Header:	`#include <AUI/Test/UI/UIMatcher.h>`
CMake:	`aui_link(my_target PUBLIC aui::uitests)`

Detailed Description#

Obtain UIMatcher from the By functions (By::text, By::name, By::type, By::exactType, By::value). The matcher does not remember views: every perform, check, one, toSet and toVector call walks all windows of the window manager and finds the views that match at that moment. Therefore, the same matcher can be reused after UI has changed.

Only views with Visibility::VISIBLE are matched (and views inside invisible containers are not reachable), unless includeInvisibleViews() is called or an assertion that ignores visibility is used (visible(), notVisible(), gone(), isParentOf).

By::text("Say hello").perform(click());
By::name("#hello").check(visible()).check(text("Hello!"));

Matchers are combined with operator| (either) and operator& (both):

(By::text("OK") | By::text("Cancel")).check(sameWidth());

perform and check return the matcher itself, so they can be chained.

Note

check fails the test when nothing is matched, and perform on an empty selection does nothing, only prints a message. Do not assume that a perform found its target.

See Finding views, Simulating user input and Checking views.

Public Methods#

allChildren#

UIMatcher UIMatcher::allChildren()

Matches the views whose parent is matched by this matcher.

Combined with parent(), selects siblings: By::name("a").parent().allChildren().

Examples:

examples/ui/views/tests/LayoutManagerTest.cpp

Views Example — All-in-one views building example.

TEST_F(UILayoutManager, ButtonsAlignment) {
    // buttons column should be perfectly aligned
    By::name("Common button")
        .parent()
        .allChildren()
        .check(leftRightAligned(), "elements should be perfectly aligned");
}

check#

template<class Assertion >
UIMatcher& UIMatcher::check(Assertion&& assertion, const char* msg = "no msg")

Checks that every matched view satisfies the assertion.

Arguments: assertion
`visible()`, `text("...")`, `width(...)` etc... or any callable `bool(const _&)`.

msg
message to print when the check fails.
Returns: this matcher, to chain further calls.

Failing is non-fatal (EXPECT_* semantics): the test continues. An empty selection fails the check.

Examples:

findNearestTo#

UIMatcher UIMatcher::findNearestTo(UIMatcher matcher)

Finds the nearest view to the specified one.

Arguments: matcher
UIMatcher of a view to find the nearest to. The UIMatcher is expected to match only one view.
Returns: the nearest view

Finds the nearest view to the bottom right corner of the specified view. The bottom right corner is chosen in order to simulate human eye scanning (which is from top-left to bottom-right).

Useful when finding fields by their labels:

_new<ALabel>("Login"),
_new<ATextField>(),
_new<ALabel>("Password"),
_new<ATextField>(),
...
By::type<ATextField>().findNearestTo(By::text("Login")) // <- matches the first ATextField
By::type<ATextField>().findNearestTo(By::text("Password")) // <- matches the second ATextField

includeInvisibleViews#

UIMatcher& UIMatcher::includeInvisibleViews()

Makes this matcher consider views that are not Visibility::VISIBLE as well.

one#

_<AView> UIMatcher::one()

Returns the first matched view, or nullptr if nothing is matched.

Use it to get the actual view for direct inspection:

auto field = _cast<ATextField>(By::name("#username").one());

The order of views is unspecified; when several views match, make the selector more precise.

parent#

UIMatcher UIMatcher::parent()

Matches containers that have a direct child matched by this matcher.

Examples:

perform#

template<class Action >
UIMatcher& UIMatcher::perform(Action&& action)

Runs an action (click(), type("..."), scroll(...) etc...) on every matched view.

Returns: this matcher, to chain further calls.

The UI is processed (uitest::frame()) before the first and after every action.