ui::testing¶

Namespace-scope declarations of ui::testing from the testing headers.

Functions¶

clear_dirty¶

void clear_dirty(Element& element, DirtyFlags flags = DirtyFlags::All)

Header: winui/testing/ElementAccess.hpp.

Clears flags on element and its subtree, as the window does after drawing a frame, so a test can then check what a change marks dirty.

Example:

ui::ButtonControl button{"Save"};
ui::testing::clear_dirty(button);
button.set_text("Save all");
REQUIRE(button.is_dirty(ui::DirtyFlags::Layout));

set_focused¶

void set_focused(Element& element, bool focused)

Header: winui/testing/ElementAccess.hpp.

Shows element focused or not, as its window does when keyboard focus arrives or leaves, for a test that drives a control on its own.

Example:

ui::TextBoxControl box;
ui::testing::set_focused(box, true);
box.handle_key(ui::KeyEvent{.key = ui::Key::End});

set_focus_visible¶

void set_focus_visible(Element& element, bool visible)

Header: winui/testing/ElementAccess.hpp.

Sets element's focus-visible state, as its window does when the input modality changes.

render_with_focus_ring¶

void render_with_focus_ring(const Element& element, Renderer& renderer, const Theme& theme = Theme::default_light())

Header: winui/testing/ElementAccess.hpp.

Draws element as its window draws the root of a tree, for a test that checks a focus ring without a Window. It draws the element, then the focus ring of the focused, focus-visible element inside it on top of everything.

Example:

ui::ButtonControl button{"Save"};
// ... measure and arrange it ...
ui::testing::set_focused(button, true);
ui::testing::TestRenderer renderer;
ui::testing::render_with_focus_ring(button, renderer);

popup_open¶

bool popup_open(const Element& element)

Header: winui/testing/ElementAccess.hpp.

Whether element has a popup open (Element::open_popup()).

Example:

ui::FlyoutControl flyout;
flyout.set_content(std::make_unique<ui::TextControl>("Saved"));
flyout.show();
REQUIRE(ui::testing::popup_open(flyout));

popup_content¶

Element* popup_content(const Element& element)

Header: winui/testing/ElementAccess.hpp.

The content of the popup element has open, or null when none is open.

popup_anchor¶

Rect popup_anchor(const Element& element)

Header: winui/testing/ElementAccess.hpp.

The window rect the popup element has open hangs from: the request's anchor (the element by default) or the rect inside it. An empty rect when none is open.

dismiss_popup¶

void dismiss_popup(Element& element)

Header: winui/testing/ElementAccess.hpp.

Dismisses the popup element has open, as its window does on a press outside it or Escape.

create_headless¶

HeadlessUI create_headless()

Header: winui/testing/HeadlessUI.hpp.

A fresh HeadlessUI, the same as HeadlessUI{}. It reads better at the top of a test.

perf_counters¶

PerfCounters perf_counters()

Header: winui/testing/PerfCounters.hpp.

The counts since the process started.

startup_milestones¶

StartupMilestones startup_milestones()

Header: winui/testing/PerfCounters.hpp.

The startup milestones reached so far.

private_bytes¶

std::uint64_t private_bytes()

Header: winui/testing/PerfCounters.hpp.

The process's private bytes (memory committed for it alone), or 0 where the platform doesn't report them.

set_clipboard¶

void set_clipboard(Clipboard* clipboard)

Header: winui/testing/TestClipboard.hpp.

Makes ui::clipboard() return clipboard for the whole process, so every control copies to and pastes from it; nullptr goes back to the platform's. Non-owning: clipboard must stay alive while installed (a TestClipboard uninstalls itself when destroyed).

Example:

ui::testing::TestClipboard clipboard;
ui::testing::set_clipboard(&clipboard);
clipboard.set_text("Portland");

auto box = std::make_unique<ui::TextBoxControl>();
ui::testing::set_focused(*box, true);
box->handle_key({ui::Key::V, ui::KeyAction::Down, {.ctrl = true}});
REQUIRE(box->text() == "Portland");

set_jump_list_host¶

void set_jump_list_host(JumpListHost* host)

Header: winui/testing/TestJumpListHost.hpp.

Makes ui::set_jump_list() and ui::add_recent_file() use host for the whole process; nullptr goes back to the platform's. Non-owning: host must stay alive while installed (a TestJumpListHost uninstalls itself when destroyed).

Example:

ui::testing::TestJumpListHost jump_list;
ui::testing::set_jump_list_host(&jump_list);
ui::set_jump_list({});
REQUIRE(jump_list.set_count == 1);

set_launcher¶

void set_launcher(Launcher* launcher)

Header: winui/testing/TestLauncher.hpp.

Makes ui::launch_uri(), ui::launch_file() and the controls that open links use launcher for the whole process; nullptr goes back to the platform's. Non-owning: launcher must stay alive while installed (a TestLauncher uninstalls itself when destroyed).

Example:

ui::testing::TestLauncher launcher;
ui::testing::set_launcher(&launcher);
ui::launch_uri("https://example.com");
REQUIRE(launcher.launched == std::vector<std::string>{"https://example.com"});

set_message_box_host¶

void set_message_box_host(MessageBoxHost* host)

Header: winui/testing/TestMessageBoxHost.hpp.

Makes ui::message_box() use host for the whole process; nullptr goes back to the platform's. Non-owning: host must stay alive while installed (a TestMessageBoxHost uninstalls itself when destroyed).

Example:

ui::testing::TestMessageBoxHost boxes;
ui::testing::set_message_box_host(&boxes);
ui::message_box({.text = "Done"});
REQUIRE(boxes.shown.size() == 1);

set_notifier¶

void set_notifier(Notifier* notifier)

Header: winui/testing/TestNotifier.hpp.

Makes ui::notify() use notifier for the whole process; nullptr goes back to the platform's. Non-owning: notifier must stay alive while installed (a TestNotifier uninstalls itself when destroyed).

Example:

ui::testing::TestNotifier notifier;
ui::testing::set_notifier(&notifier);
ui::notify({.title = "Done"});
REQUIRE(notifier.shown.size() == 1);

set_print_host¶

void set_print_host(PrintHost* host)

Header: winui/testing/TestPrintHost.hpp.

Installs host as what ui::print() uses, or nullptr for the platform's own.

describe¶

std::string describe(const Window& window)

Header: winui/testing/TestRenderer.hpp.

Renders window through a TestRenderer and prints the result with ui::describe(): the semantic golden of a whole window. Lay the window out first; the dump starts with the theme's SetRasterization line.

Example:

// What the window draws right now, as text, to diff against an earlier frame.
const std::string frame = ui::testing::describe(window);
std::println("{}", frame);