morph::ui::testing::RecordingBackend: a headless widget tree with an operation log, a golden dump and user-interaction helpers — the test double and the reference for every real backend. More...

#include <algorithm>
#include <cctype>
#include <cstddef>
#include <cstdint>
#include <format>
#include <functional>
#include <initializer_list>
#include <map>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <unordered_map>
#include <unordered_set>
#include <utility>
#include <variant>
#include <vector>
#include "../../util/datetime.hpp"
#include "../backend.hpp"
#include "../view.hpp"

Classes
struct	morph::ui::testing::detail::Callbacks
	The handlers a widget was given, which the interaction helpers call. More...
struct	morph::ui::testing::detail::Record
	One fake widget's state. More...
class	morph::ui::testing::detail::RecordStore
	The records, the roots and the operation log that every fake widget of one backend writes to. More...
class	morph::ui::testing::detail::FakeLeaf< Interface >
	The Widget half of every fake: records itself on construction, records Common's setters, and records its destruction. More...
class	morph::ui::testing::detail::FakeContainer< Interface >
	The ContainerWidget half of every fake container. More...
class	morph::ui::testing::detail::FakeField< Interface >
	The FieldWidget half of every fake field: properties readonly, required, errors, stale. More...
class	morph::ui::testing::detail::FakeText
	A fake TextWidget: properties text, role. More...
class	morph::ui::testing::detail::FakeButton
	A fake ButtonWidget: properties label, emphasis, icon, style and selected. More...
class	morph::ui::testing::detail::FakeTextInput
	A fake TextInputWidget: properties mode, text, placeholder, unit, decimals, icon, caption, captionShown, the field state, and a text cursor. More...
class	morph::ui::testing::detail::FakeCheckbox
	A fake CheckboxWidget: properties label, checked. More...
class	morph::ui::testing::detail::FakeSelect
	A fake SelectWidget: properties style, options, selected, caption, captionShown. More...
class	morph::ui::testing::detail::FakeMenu
	A fake MenuWidget: property items. More...
class	morph::ui::testing::detail::FakeStack
	A fake StackWidget, of kind Column or Row: properties gap, align, justify. More...
class	morph::ui::testing::detail::FakeGrid
	A fake GridWidget: properties columns, gap, align, and span on a child. More...
class	morph::ui::testing::detail::FakePanel
	A fake PanelWidget: properties title, header (the child's id), padding, collapsible, collapsed. More...
class	morph::ui::testing::detail::FakeBusy
	A fake BusyWidget: properties active, label. More...
class	morph::ui::testing::detail::FakeDateTimeInput
	A fake DateTimeInputWidget: properties mode, offset, value, caption, captionShown. More...
class	morph::ui::testing::detail::FakeSlider
	A fake SliderWidget: properties range (minimum..maximum/step), value. More...
class	morph::ui::testing::detail::FakeFilePicker
	A fake FilePickerWidget: properties mode, path. More...
class	morph::ui::testing::detail::FakeTabs
	A fake TabsWidget: properties tabs, selected, barShown. More...
class	morph::ui::testing::detail::FakeOverlay< Interface >
	A fake overlay's footer: a Footer child, made when it is first asked for, so an overlay that never shows actions logs none. More...
class	morph::ui::testing::detail::FakeDialog
	A fake DialogWidget: properties open, title; a Footer child once its footer is asked for. More...
class	morph::ui::testing::detail::FakeBanner
	A fake BannerWidget: properties tone, text, actionLabel, dismissible. More...
class	morph::ui::testing::detail::FakeToast
	A fake ToastWidget: properties text, tone, and shown (incremented on every show, so a test can tell a replace from a no-op). More...
class	morph::ui::testing::detail::FakeBadge
	A fake BadgeWidget: properties tone, text, icon. More...
class	morph::ui::testing::detail::FakeProgress
	A fake ProgressWidget: properties value (as formatFraction gives it), label. More...
class	morph::ui::testing::detail::FakeSteps
	A fake StepsWidget: properties steps ([label:State,…]), current (a position, or none). More...
class	morph::ui::testing::detail::FakeKeyValue
	A fake KeyValueWidget: property items ([label:value,…]). More...
class	morph::ui::testing::detail::FakeEmptyState
	A fake EmptyStateWidget: properties title, text, icon, actionLabel. More...
class	morph::ui::testing::detail::FakeDrawer
	A fake DrawerWidget: properties side, open, title; a Footer child once its footer is asked for. More...
class	morph::ui::testing::detail::FakeSplitter
	A fake SplitterWidget: properties axis, sizes ([n,…]). More...
class	morph::ui::testing::detail::FakeCollapsible
	A fake CollapsibleWidget: properties title, header (the header child's id), open. More...
class	morph::ui::testing::detail::FakeDropZone
	A fake DropZoneWidget: properties accept ([.ext,…]), multiple. More...
class	morph::ui::testing::detail::FakeCustom
	A fake loaded CustomWidget: property component, and each prop as prop.<name>. More...
class	morph::ui::testing::detail::FakeTable
	A fake TableWidget: properties columns, selectionMode, selection, and rowKey on a row. More...
class	morph::ui::testing::RecordingBackend
	A headless IViewBackend: fake widgets that record every operation, a golden dump of the live tree, and helpers that act as the user would. More...

Typedefs
using	morph::ui::testing::detail::PropList = std::vector<std::pair<std::string, std::string>>
	Properties fixed when a widget is created, as name and formatted value.

Functions
std::string	morph::ui::testing::detail::formatBool (bool value)
	Formats a flag.
template<typename Special>
std::string	morph::ui::testing::detail::escape (std::string_view text, Special const &isSpecial)
	Escapes text with a backslash: a line break becomes backslash and n, a carriage return backslash and r, and a backslash or a character `isSpecial` selects is preceded by a backslash.
std::string	morph::ui::testing::detail::formatText (std::string_view text)
	Formats free text as a property value. Line breaks and = are escaped, so the value stays on its own line and no part of it reads as another name=value.
std::string	morph::ui::testing::detail::formatItem (std::string_view text)
	Formats free text as an element of a formatList list. Also escapes ,, [ and ], so the text reads as one element.
std::string	morph::ui::testing::detail::formatMenu (std::vector< MenuEntry > const &entries)
	Formats a menu's entries: [a,b], each entry its label followed by the attributes that differ from the default, as ;icon=x, ;keys=x, ;checked=true or ;checked=false, and ;enabled=false, then its submenu in brackets. A flat menu of plain entries reads [Open,Quit].
std::string	morph::ui::testing::detail::formatKey (Key const &key)
	Formats a key: an integer in decimal, a string in double quotes, so 7 and "7" differ.
std::string	morph::ui::testing::detail::formatOptionalKey (std::optional< Key > const &key)
	Formats an optional key.
std::string	morph::ui::testing::detail::formatSizing (Sizing sizing)
	Formats one dimension's sizing.
std::string	morph::ui::testing::detail::formatAlign (Align align)
	Formats an alignment.
std::string	morph::ui::testing::detail::formatJustify (Justify justify)
	Formats a justification.
std::string	morph::ui::testing::detail::formatLayout (LayoutHints const &hints)
	Formats a size request.
std::string	morph::ui::testing::detail::formatTimestamp (std::optional< morph::time::Timestamp > const &value)
	Formats a date-time value.
template<typename T, typename F>
std::string	morph::ui::testing::detail::formatList (std::vector< T > const &items, F const &each)
	Formats a list as [a,b,c].
std::string	morph::ui::testing::detail::enumName (ButtonEmphasis emphasis)
	A button emphasis's name.
std::string	morph::ui::testing::detail::enumName (ButtonStyle style)
	A button style's name.
std::string	morph::ui::testing::detail::enumName (TextRole role)
	A text role's name.
std::string	morph::ui::testing::detail::enumName (TextInputMode mode)
	A text input mode's name.
std::string	morph::ui::testing::detail::enumName (SelectStyle style)
	A select style's name.
std::string	morph::ui::testing::detail::enumName (Tone tone)
	A tone's name.
std::string	morph::ui::testing::detail::enumName (Side side)
	A side's name.
std::string	morph::ui::testing::detail::enumName (StepState state)
	A step state's name.
std::string	morph::ui::testing::detail::formatFraction (std::optional< double > value)
	A fraction as its shortest decimal text, or none.
std::string	morph::ui::testing::detail::enumName (Axis axis)
	An axis's name.
std::string	morph::ui::testing::detail::enumName (DateMode mode)
	A date mode's name.
std::string	morph::ui::testing::detail::enumName (FilePickerMode mode)
	A file picker mode's name.
std::string	morph::ui::testing::detail::enumName (SelectionMode mode)
	A selection mode's name.

Detailed Description

morph::ui::testing::RecordingBackend: a headless widget tree with an operation log, a golden dump and user-interaction helpers — the test double and the reference for every real backend.

Specified in docs/spec/ui/backend_contract.md, "RecordingBackend".

Definition in file recording_backend.hpp.

Typedef Documentation

◆ PropList

using morph::ui::testing::detail::PropList = std::vector<std::pair<std::string, std::string>>

Properties fixed when a widget is created, as name and formatted value.

Definition at line 38 of file recording_backend.hpp.

Function Documentation

◆ formatBool()

std::string morph::ui::testing::detail::formatBool ( bool value )

inlinenodiscard

Formats a flag.

Parameters

value The flag.

Returns: true or false.

Definition at line 43 of file recording_backend.hpp.

◆ escape()

template<typename Special>

std::string morph::ui::testing::detail::escape	(	std::string_view	text,
		Special const &	isSpecial )

nodiscard

Escapes text with a backslash: a line break becomes backslash and n, a carriage return backslash and r, and a backslash or a character isSpecial selects is preceded by a backslash.

Template Parameters

Special A callable taking a char and returning whether to escape it.

Parameters

text	The text.
isSpecial	Selects the characters to escape besides the backslash and the two line-ending characters.

Returns: The escaped text.

Definition at line 52 of file recording_backend.hpp.

◆ formatText()

std::string morph::ui::testing::detail::formatText ( std::string_view text )

inlinenodiscard

Formats free text as a property value. Line breaks and = are escaped, so the value stays on its own line and no part of it reads as another name=value.

Parameters

text	The text, UTF-8.

Returns: The escaped text.

Definition at line 74 of file recording_backend.hpp.

◆ formatItem()

std::string morph::ui::testing::detail::formatItem ( std::string_view text )

inlinenodiscard

Formats free text as an element of a formatList list. Also escapes ,, [ and ], so the text reads as one element.

Parameters

text	The text, UTF-8.

Returns: The escaped text.

Definition at line 82 of file recording_backend.hpp.

◆ formatMenu()

std::string morph::ui::testing::detail::formatMenu ( std::vector< MenuEntry > const & entries )

inlinenodiscard

Formats a menu's entries: [a,b], each entry its label followed by the attributes that differ from the default, as ;icon=x, ;keys=x, ;checked=true or ;checked=false, and ;enabled=false, then its submenu in brackets. A flat menu of plain entries reads [Open,Quit].

Parameters

entries The entries.

Returns: Their text; =, ,, [, ] and ; in a label or attribute are escaped.

Definition at line 92 of file recording_backend.hpp.

◆ formatKey()

std::string morph::ui::testing::detail::formatKey ( Key const & key )

inlinenodiscard

Formats a key: an integer in decimal, a string in double quotes, so 7 and "7" differ.

Parameters

key The key.

Returns: Its text. A string key is escaped as formatItem escapes, and a double quote in it is preceded by a backslash.

Definition at line 123 of file recording_backend.hpp.

◆ formatOptionalKey()

std::string morph::ui::testing::detail::formatOptionalKey ( std::optional< Key > const & key )

inlinenodiscard

Formats an optional key.

Parameters

key	The key, or none.

Returns: formatKey(*key), or none.

Definition at line 136 of file recording_backend.hpp.

◆ formatSizing()

std::string morph::ui::testing::detail::formatSizing ( Sizing sizing )

inlinenodiscard

Formats one dimension's sizing.

Parameters

sizing The sizing.

Returns: content, fixed(n) or stretch(n).

Definition at line 143 of file recording_backend.hpp.

◆ formatAlign()

std::string morph::ui::testing::detail::formatAlign ( Align align )

inlinenodiscard

Formats an alignment.

Parameters

align The alignment.

Returns: stretch, start, center or end.

Definition at line 159 of file recording_backend.hpp.

◆ formatJustify()

std::string morph::ui::testing::detail::formatJustify ( Justify justify )

inlinenodiscard

Formats a justification.

Parameters

justify The justification.

Returns: start, center, end or between.

Definition at line 176 of file recording_backend.hpp.

◆ formatLayout()

std::string morph::ui::testing::detail::formatLayout ( LayoutHints const & hints )

inlinenodiscard

Formats a size request.

Parameters

hints The request.

Returns: width/height, each as formatSizing gives it and followed by min=<n> and max=<n> for the bounds it has, then self=<align> when the node places itself, such as stretch(1) max=44/content self=center.

Definition at line 194 of file recording_backend.hpp.

◆ formatTimestamp()

std::string morph::ui::testing::detail::formatTimestamp ( std::optional< morph::time::Timestamp > const & value )

inlinenodiscard

Formats a date-time value.

Parameters

value The value.

Returns: none for nullopt, empty for an empty Timestamp, else the ISO-8601 UTC instant.

Definition at line 213 of file recording_backend.hpp.

◆ formatList()

template<typename T, typename F>

std::string morph::ui::testing::detail::formatList	(	std::vector< T > const &	items,
		F const &	each )

nodiscard

Formats a list as [a,b,c].

Template Parameters

T	The element type.
F	A callable turning a T const& into a std::string.

Parameters

items	The elements.
each	Formats one element.

Returns: The list's text.

Definition at line 230 of file recording_backend.hpp.

◆ enumName() [1/12]

std::string morph::ui::testing::detail::enumName ( ButtonEmphasis emphasis )

inlinenodiscard

A button emphasis's name.

Parameters

emphasis The emphasis.

Returns: The enumerator's name.

Definition at line 246 of file recording_backend.hpp.

◆ enumName() [2/12]

std::string morph::ui::testing::detail::enumName ( ButtonStyle style )

inlinenodiscard

A button style's name.

Parameters

style The style.

Returns: The enumerator's name.

Definition at line 263 of file recording_backend.hpp.

◆ enumName() [3/12]

std::string morph::ui::testing::detail::enumName ( TextRole role )

inlinenodiscard

A text role's name.

Parameters

role The role.

Returns: The enumerator's name.

Definition at line 268 of file recording_backend.hpp.

◆ enumName() [4/12]

std::string morph::ui::testing::detail::enumName ( TextInputMode mode )

inlinenodiscard

A text input mode's name.

Parameters

mode The mode.

Returns: The enumerator's name.

Definition at line 290 of file recording_backend.hpp.

◆ enumName() [5/12]

std::string morph::ui::testing::detail::enumName ( SelectStyle style )

inlinenodiscard

A select style's name.

Parameters

style The style.

Returns: The enumerator's name.

Definition at line 306 of file recording_backend.hpp.

◆ enumName() [6/12]

std::string morph::ui::testing::detail::enumName ( Tone tone )

inlinenodiscard

A tone's name.

Parameters

tone The tone.

Returns: The enumerator's name.

Definition at line 320 of file recording_backend.hpp.

◆ enumName() [7/12]

std::string morph::ui::testing::detail::enumName ( Side side )

inlinenodiscard

A side's name.

Parameters

side The side.

Returns: The enumerator's name.

Definition at line 340 of file recording_backend.hpp.

◆ enumName() [8/12]

std::string morph::ui::testing::detail::enumName ( StepState state )

inlinenodiscard

A step state's name.

Parameters

state The state.

Returns: The enumerator's name.

Definition at line 354 of file recording_backend.hpp.

◆ formatFraction()

std::string morph::ui::testing::detail::formatFraction ( std::optional< double > value )

inlinenodiscard

A fraction as its shortest decimal text, or none.

Parameters

value The fraction.

Returns: The text, such as 0.25.

Definition at line 372 of file recording_backend.hpp.

◆ enumName() [9/12]

std::string morph::ui::testing::detail::enumName ( Axis axis )

inlinenodiscard

An axis's name.

Parameters

axis The axis.

Returns: The enumerator's name.

Definition at line 382 of file recording_backend.hpp.

◆ enumName() [10/12]

std::string morph::ui::testing::detail::enumName ( DateMode mode )

inlinenodiscard

A date mode's name.

Parameters

mode The mode.

Returns: The enumerator's name.

Definition at line 396 of file recording_backend.hpp.

◆ enumName() [11/12]

std::string morph::ui::testing::detail::enumName ( FilePickerMode mode )

inlinenodiscard

A file picker mode's name.

Parameters

mode The mode.

Returns: The enumerator's name.

Definition at line 410 of file recording_backend.hpp.

◆ enumName() [12/12]

std::string morph::ui::testing::detail::enumName ( SelectionMode mode )

inlinenodiscard

A selection mode's name.

Parameters

mode The mode.

Returns: The enumerator's name.

Definition at line 424 of file recording_backend.hpp.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ PropList

Function Documentation

◆ formatBool()

◆ escape()

◆ formatText()

◆ formatItem()

◆ formatMenu()

◆ formatKey()

◆ formatOptionalKey()

◆ formatSizing()

◆ formatAlign()

◆ formatJustify()

◆ formatLayout()

◆ formatTimestamp()

◆ formatList()

◆ enumName() [1/12]

◆ enumName() [2/12]

◆ enumName() [3/12]

◆ enumName() [4/12]

◆ enumName() [5/12]

◆ enumName() [6/12]

◆ enumName() [7/12]

◆ enumName() [8/12]

◆ formatFraction()

◆ enumName() [9/12]

◆ enumName() [10/12]

◆ enumName() [11/12]

◆ enumName() [12/12]