Masonry Testing

Headless Test Harness for Masonry

Headless runner for testing Masonry applications.

The primary type from this crate is [TestHarness], which creates a host for any [Widget]. The widget can of course have children, which allows this crate to be used for testing entire applications.

The testing harness can:

Simulate any external event which Masonry handles, including mouse movement, key presses, text input, accessibility events.
Control the flow of time to the application (i.e. for testing animations).
Take screenshots of the application, save these to a file, and ensure that these are up-to-date. See Screenshots for more details.

Testing in Masonry is also documented in the Testing widgets in Masonry chapter in Masonry's book.

This crate can be accessed for applications using Masonry as masonry::testing, if Masonry's testing feature is enabled. For applications which are using only Masonry Core, you should depend on masonry_testing directly.

Screenshots

Tests using TestHarness can include snapshot steps by using the [assert_render_snapshot] screenshot. This renders the application being tested, then compares it against the png file with the given name from the screenshots folder (in the package being tested, i.e. adjacent to its Cargo.toml file).

Masonry Testing will update the reference file when the MASONRY_TEST_BLESS environment variable has a value of 1. This can be used if the file doesn't exist, or there's an expected difference. The screenshots are losslessly compressed (using [oxipng]) and limited to a small maximum file size (this limit has an escape hatch). This ensures that the screenshots are small enough to embed in a git repository with limited risk of clone times growing unreasonably. UI screenshots compress well, so we expect this to be scalable.

For repositories hosted on GitHub, this scheme also allows for including screenshots of your app or widgets in hosted documentation, although we haven't documented this publicly yet.

Examples

For examples of this crate in use

To test applications: see the tests in Masonry's examples.
To test widgets: see the tests module in each widget in Masonry.

Minimum supported Rust Version (MSRV)

This version of Masonry Testing has been verified to compile with Rust 1.88 and later.

Future versions of Masonry Testing might increase the Rust version requirement. It will not be treated as a breaking change and as such can even happen with small patch releases.

Community

Discussion of Masonry Testing development happens in the Linebender Zulip, specifically the #masonry channel. All public content can be read without logging in.

Contributions are welcome by pull request. The Rust code of conduct applies.

License