web_sys_ec/lib.rs
1#![cfg_attr(feature = "nightly", feature(async_fn_track_caller))]
2
3//! [](https://crates.io/crates/web-sys-ec)
4//! [](https://github.com/mondeja/web-sys-ec/blob/master/LICENSE)
5//! [](https://github.com/mondeja/web-sys-ec/actions)
6//! [](https://docs.rs/web-sys-ec)
7//! [](https://crates.io/crates/web-sys-ec)
8//!
9//! Expected conditions in Selenium-like style for WASM targets using [`web-sys`].
10//!
11//! # Rationale
12//!
13//! When you test your apps with `wasm-pack test`, you may want to use the
14//! [`web-sys`] crate to interact with the DOM. This is a great way to test your
15//! app in a real browser environment.
16//!
17//! However, actions in a browser are asynchronous, and you may want to wait for
18//! certain conditions to be met while testing. This is where `web-sys-ec` comes
19//! in.
20//!
21//! Provides an interface to interact with the DOM waiting for certain conditions
22//! to be met. It is inspired by the Selenium syntax, where you can wait for
23//! certain expected conditions to be met before proceeding with your tests.
24//!
25//! # Disclaimer
26//!
27//! I've created this library to help me with my own testing needs and it's far
28//! away from being complete. Feel free to open pull requests or issues if you
29//! find any bugs or have suggestions for improvements and I'll be happy to
30//! review them.
31//!
32//! # Installation
33//!
34//! Add `web-sys-ec` to your `Cargo.toml`:
35//!
36//! ```toml
37//! [dependencies]
38//! web-sys-ec = "0.1"
39//! ```
40//!
41//! # Usage
42//!
43//! Wait 10 seconds for a `<p>` HTML element to contain the text `"Select a language:"`:
44//!
45//! ```rust,ignore
46//! use web_sys_ec::{By, Ec, Wait};
47//!
48//! Wait(10)
49//! .until((
50//! By::TagName("p"),
51//! Ec::InnerTextContains("Select a language:"),
52//! ))
53//! .await;
54//! ```
55//!
56//! Wait 1 second for the `<html>` HTML element to have the `lang` attribute set to
57//! `"es"`:
58//!
59//! ```rust,ignore
60//! use web_sys_ec::{By, Ec, Wait};
61//!
62//! Wait(1)
63//! .until((
64//! By::TagName("html"),
65//! Ec::AttributeValueIs("lang", "es"),
66//! ))
67//! .await;
68//! ```
69//!
70//! Wait 1 second for the local storage to have the `language` key set to `"es"`:
71//!
72//! ```rust,ignore
73//! use web_sys_ec::{Ec, Wait};
74//!
75//! Wait(1).until(Ec::LocalStorageAttributeValueIs("language","es")).await;
76//! ```
77//!
78//! Wait 200 milliseconds for a `<p id="foo">` HTML element to exist in the DOM:
79//!
80//! ```rust,ignore
81//! use web_sys_ec::{By, Wait};
82//!
83//! Wait(0.2).until("p#foo").await;
84//! ```
85//!
86//! If a condition is not met, it will panic with a message like:
87//!
88//! <!-- markdownlint-disable MD013 -->
89//!
90//! ```txt
91//! Expected condition has not been met in the given time:
92//! - Caller: tests/end2end/tests/csr_complete.rs:54:10
93//! - Selector: HTML element with tag name 'html' (`By::TagName("html")`)
94//! - Condition: HTML element attribute 'lang' value is equal to 'es' (`Ec::AttributeValueIs("lang", "es")`)
95//! - Duration: 1s
96//! - Poll frecuency: 20ms
97//! - Number of attempts: 51
98//! ```
99//!
100//! <!-- markdownlint-enable MD013 -->
101//!
102//! Note that the `Caller: ...` line will only be shown if you're using the `nightly`
103//! toolchain and the `nightly` feature is enabled.
104//!
105//! # Features
106//!
107//! - `nightly`: Enables nightly toolchain support, which is currently needed to
108//! provide caller tracking.
109//!
110//! [`web-sys`]: https://crates.io/crates/web-sys
111
112pub(crate) mod by;
113mod condition;
114pub(crate) mod ec;
115mod until;
116mod wait;
117mod wait_options;
118
119pub use by::By;
120pub(crate) use condition::Condition;
121pub use ec::Ec;
122pub(crate) use until::{until_impl, until_not_impl};
123pub use wait::Wait;
124#[doc(hidden)]
125pub(crate) use wait::Wait as Waiter;
126pub use wait_options::WaitOptions;