Introduce a crate to write unit tests of Dioxus apps

[hovinen]

This is a preliminary version of a library in the spirit of React or Flutter to allow easy unit testing of Dioxus apps.

Right now it only supports the click event, but I believe that is sufficient to show the design. Once the overall design is finalised, it can be fully fleshed out.

I placed this directly in the Dioxus repository. I'm also fine with keeping it as a separate crate if desired. However, this requires a few small changes to the dioxus-native crate to allow the creation of synthetic events. Otherwise the existing visibility restrictions make it impossible to dispatch DOM events from the test.

I decided to add fairly fleshed out documentation including doctests so as to illustrate the use of the library. I have tested it against a personal project and it is working quite well.

Alternatives considered

• Writing a new renderer. I had considered this but found that it would be pretty much a duplicate of the existing dioxus-native.
• Dispatching events via Document::handle_ui_event. This would mean that the events would act more like real user-generated events, where, say, a click happens at particular coordinates and the framework identifies the element which is hit. This would be more "realistic" in the sense that a click on a button which is covered by another element would not hit the button but rather the element covering it. However, the UiEvent enum from Blitz does not support a "click" event and I did not want to create multiple PRs in different repositories for now.

Fixes #5324

[ealmloff]

Very excited about this, thanks for working on it!

Instead of requiring explicit event pumping, we could mimic the Playwright test API and make queries asynchronously run the event loop:

let mut tester = dioxus_test::render(AComponent).build();
// Wait for make-request-button to load and click it to make a network request.
tester.find_by_test_id("make-request-button").click().await?;
// Assert on the state of the UI while the network request is in flight.
expect(tester.find_by_test_id("loading-indicator")).to_be_visible().await?;
// Receive the server response and assert on the state of the UI after the response
// is received and the UI has been rerendered.
expect(tester.find_by_test_id("resolved-content")).to_be_visible().await?;

In some cases, waiting for work and applying a single tick of DOM operations could provide more control over testing, but I think the familiarity of the Playwright-style API and intuitive behavior in the presence of feedback loops with DOM events are typically more important.

For example, onmounted and use_effect will only trigger after the document has applied edits. With the current model, I think that would require rendering, then waiting for a 0ms timeout, then asserting the state has changed based on the onmounted event. If asserting on that state also pumped the DOM, you could just assert the state is correct directly.

[hovinen]

Thanks -- let me try this and see what I can come up with.

[hovinen]

Hi Evan, thanks for your patience on this. It took me a while to find a workable structure for this, and I admittedly didn't have as much to work on it as I would have liked.

I settled on a second layer on top of the initial API. So one can use the pump method to drive the event loop, but there's a higher level API which lets the caller await conditions on the DOM and assert on those.

Since the tester doesn't know when all async operations have fully settled, it has to rely on heuristics to some degree. It tries up to a maximum number of attempts to obtain an element or to make an assertion and gives up eventually. The pump method is similarly equipped with a timeout since I don't have an easy way to detect whether it would just wait forever.

I had to introduce some new concepts to support assertions in this model. A given element on which the test is to assert might already be present but have the wrong state at the time the assertion is invoked. So there needs to be a concept of "assert that this is eventually true, even if it's not true right now." To support this, I introduced matchers similar to the GoogleTest crate. These can be passed into the tester which can just repeatedly try the assertion until it's true, giving up after a maximum number of tries.

I've tried this out on a private project and the API seems reasonable.

There are some more TODOs on this: I need to update the overall docs and I'd like to make some improvements to the API. But this should at least convey the idea.

Please let me know what you think. Thanks!

[ealmloff]

Much nicer! We could make this more composable by extracting a poll once or await helper so you can do something like:

tester.get("selector").immediately()?;
tester.get("selector").await?;
tester.get("selector").expect(inner_html(to_contain("hello"))).await?;
tester.get("selector").expect(inner_html(to_contain("hello"))).immediately()?;

It isn't fully built out yet, but I have a prototype in this commit: 358b9ed

[hovinen]

Interesting! I had played around trying to build a fluent interface like that but found that whatever the query method on DocumentTester returned had to contain an exclusive reference to DocumentTester, which caused no end of problems. I admittedly didn't consider implementing IntoFuture directly.

I'll play around with your prototype and see how well it works in the project I am doing.