matrix_sdk/test_utils/
mod.rs

1//! Testing utilities - DO NOT USE IN PRODUCTION.
2
3#![allow(dead_code)]
4
5use assert_matches2::assert_let;
6use matrix_sdk_base::{deserialized_responses::TimelineEvent, store::RoomLoadSettings};
7use ruma::{
8    api::MatrixVersion,
9    events::{room::message::MessageType, AnySyncMessageLikeEvent, AnySyncTimelineEvent},
10};
11use url::Url;
12
13pub mod client;
14#[cfg(not(target_family = "wasm"))]
15pub mod mocks;
16
17use self::client::mock_matrix_session;
18use crate::{config::RequestConfig, Client, ClientBuilder};
19
20/// Checks that an event is a message-like text event with the given text.
21#[track_caller]
22pub fn assert_event_matches_msg<E: Clone + Into<TimelineEvent>>(event: &E, expected: &str) {
23    let event: TimelineEvent = event.clone().into();
24    let event = event.raw().deserialize().unwrap();
25    assert_let!(
26        AnySyncTimelineEvent::MessageLike(AnySyncMessageLikeEvent::RoomMessage(message)) = event
27    );
28    let message = message.as_original().unwrap();
29    assert_let!(MessageType::Text(text) = &message.content.msgtype);
30    assert_eq!(text.body, expected);
31}
32
33/// A [`ClientBuilder`] fit for testing, using the given `homeserver_url` (or
34/// localhost:1234).
35pub fn test_client_builder(homeserver_url: Option<String>) -> ClientBuilder {
36    let homeserver = homeserver_url
37        .map(|url| Url::try_from(url.as_str()).unwrap())
38        .unwrap_or_else(|| Url::try_from("http://localhost:1234").unwrap());
39    Client::builder().homeserver_url(homeserver).server_versions([MatrixVersion::V1_0])
40}
41
42/// A [`Client`] using the given `homeserver_url` (or localhost:1234), that will
43/// never retry any failed requests.
44pub async fn no_retry_test_client(homeserver_url: Option<String>) -> Client {
45    test_client_builder(homeserver_url)
46        .request_config(RequestConfig::new().disable_retry())
47        .build()
48        .await
49        .unwrap()
50}
51
52/// Restore the common (Matrix-auth) user session for a client.
53pub async fn set_client_session(client: &Client) {
54    client
55        .matrix_auth()
56        .restore_session(mock_matrix_session(), RoomLoadSettings::default())
57        .await
58        .unwrap();
59}
60
61/// A [`Client`] using the given `homeserver_url` (or localhost:1234), that will
62/// never retry any failed requests, and already logged in with an hardcoded
63/// Matrix authentication session (the user id and device id are hardcoded too).
64pub async fn logged_in_client(homeserver_url: Option<String>) -> Client {
65    let client = no_retry_test_client(homeserver_url).await;
66    set_client_session(&client).await;
67    client
68}
69
70/// Like [`test_client_builder`], but with a mocked server too.
71#[cfg(not(target_family = "wasm"))]
72pub async fn test_client_builder_with_server() -> (ClientBuilder, wiremock::MockServer) {
73    let server = wiremock::MockServer::start().await;
74    let builder = test_client_builder(Some(server.uri()));
75    (builder, server)
76}
77
78/// Like [`no_retry_test_client`], but with a mocked server too.
79#[cfg(not(target_family = "wasm"))]
80pub async fn no_retry_test_client_with_server() -> (Client, wiremock::MockServer) {
81    let server = wiremock::MockServer::start().await;
82    let client = no_retry_test_client(Some(server.uri().to_string())).await;
83    (client, server)
84}
85
86/// Like [`logged_in_client`], but with a mocked server too.
87#[cfg(not(target_family = "wasm"))]
88pub async fn logged_in_client_with_server() -> (Client, wiremock::MockServer) {
89    let server = wiremock::MockServer::start().await;
90    let client = logged_in_client(Some(server.uri().to_string())).await;
91    (client, server)
92}
93
94/// Asserts that the next item in a `Stream` is received within a given timeout.
95///
96/// This macro waits for the next item from an asynchronous `Stream` or, if no
97/// item is received within the specified timeout, the macro panics.
98///
99/// # Parameters
100///
101/// - `$stream`: The `Stream` or `Subscriber` to poll for the next item.
102/// - `$timeout_ms` (optional): The timeout in milliseconds to wait for the next
103///   item. Defaults to 500ms if not provided.
104///
105/// # Example
106///
107/// ```rust
108/// use futures_util::{stream, StreamExt};
109/// use matrix_sdk::assert_next_with_timeout;
110///
111/// # async {
112/// let mut stream = stream::iter(vec![1, 2, 3]);
113/// let next_item = assert_next_with_timeout!(stream, 1000); // Waits up to 1000ms
114/// assert_eq!(next_item, 1);
115///
116/// // The timeout can be omitted, in which case it defaults to 500 ms.
117/// let next_item = assert_next_with_timeout!(stream); // Waits up to 500ms
118/// assert_eq!(next_item, 2);
119/// # };
120/// ```
121#[macro_export]
122macro_rules! assert_next_with_timeout {
123    ($stream:expr) => {
124        $crate::assert_next_with_timeout!($stream, 500)
125    };
126    ($stream:expr, $timeout_ms:expr) => {{
127        // Needed for subscribers, as they won't use the StreamExt features
128        #[allow(unused_imports)]
129        use futures_util::StreamExt as _;
130        tokio::time::timeout(std::time::Duration::from_millis($timeout_ms), $stream.next())
131            .await
132            .expect("Next event timed out")
133            .expect("No next event received")
134    }};
135}
136
137/// Asserts the next item in a `Receiver` can be loaded in the given timeout in
138/// milliseconds.
139#[macro_export]
140macro_rules! assert_recv_with_timeout {
141    ($receiver:expr, $timeout_ms:expr) => {{
142        tokio::time::timeout(std::time::Duration::from_millis($timeout_ms), $receiver.recv())
143            .await
144            .expect("Next event timed out")
145            .expect("No next event received")
146    }};
147}
148
149/// Assert the next item in a `Stream` or `Subscriber` matches the provided
150/// pattern in the given timeout in milliseconds.
151///
152/// If no timeout is provided, a default `100ms` value will be used.
153#[macro_export]
154macro_rules! assert_next_matches_with_timeout {
155    ($stream:expr, $pat:pat) => {
156        $crate::assert_next_matches_with_timeout!($stream, $pat => {})
157    };
158    ($stream:expr, $pat:pat => $arm:expr) => {
159        $crate::assert_next_matches_with_timeout!($stream, 100, $pat => $arm)
160    };
161    ($stream:expr, $timeout_ms:expr, $pat:pat => $arm:expr) => {
162        match $crate::assert_next_with_timeout!(&mut $stream, $timeout_ms) {
163            $pat => $arm,
164            val => {
165                ::core::panic!(
166                    "assertion failed: `{:?}` does not match `{}`",
167                    val, ::core::stringify!($pat)
168                );
169            }
170        }
171    };
172}
173
174/// Asserts that the next item from an asynchronous stream is equal to the
175/// expected value, with an optional timeout and custom error message.
176///
177/// # Arguments
178///
179/// * `$stream` - The asynchronous stream to retrieve the next item from.
180/// * `$expected` - The expected value to assert against.
181/// * `$timeout ms` (optional) - A timeout in milliseconds (e.g., `200ms`).
182///   Defaults to `100ms`.
183/// * `$msg` (optional) - A formatted message string for assertion failure.
184///
185/// # Examples
186///
187/// ```
188/// # async {
189/// # use matrix_sdk::assert_next_eq_with_timeout;
190/// # use tokio_stream::StreamExt;
191///
192/// let mut stream = tokio_stream::iter(vec![42]);
193/// assert_next_eq_with_timeout!(stream, 42);
194///
195/// let mut stream = tokio_stream::iter(vec![42]);
196/// assert_next_eq_with_timeout!(stream, 42, 200 ms);
197///
198/// let mut stream = tokio_stream::iter(vec![42]);
199/// assert_next_eq_with_timeout!(
200///     stream,
201///     42,
202///     "Expected 42 but got something else"
203/// );
204///
205/// let mut stream = tokio_stream::iter(vec![42]);
206/// assert_next_eq_with_timeout!(stream, 42, 200 ms, "Expected 42 within 200ms");
207/// # };
208/// ```
209#[macro_export]
210macro_rules! assert_next_eq_with_timeout {
211    ($stream:expr, $expected:expr) => {
212        $crate::assert_next_eq_with_timeout_impl!($stream, $expected, std::time::Duration::from_millis(100));
213    };
214    ($stream:expr, $expected:expr, $timeout:literal ms) => {
215        $crate::assert_next_eq_with_timeout_impl!($stream, $expected, std::time::Duration::from_millis($timeout));
216    };
217    ($stream:expr, $expected:expr, $timeout:literal ms, $($msg:tt)*) => {
218        $crate::assert_next_eq_with_timeout_impl!($stream, $expected, std::time::Duration::from_millis($timeout), $($msg)*);
219    };
220    ($stream:expr, $expected:expr, $($msg:tt)*) => {
221        $crate::assert_next_eq_with_timeout_impl!($stream, $expected, std::time::Duration::from_millis(100), $($msg)*);
222    };
223}
224
225/// Given a [`TimelineEvent`] assert that the event was decrypted and that the
226/// message matches the expected value.
227///
228/// # Examples
229///
230/// ```no_run
231/// # async {
232/// # let client: matrix_sdk::Client = unreachable!();
233/// # let room_id: ruma::OwnedRoomId = unreachable!();
234/// # let event_id: ruma::OwnedEventId = unreachable!();
235/// use matrix_sdk::assert_decrypted_message_eq;
236///
237/// let room =
238///     client.get_room(&room_id).expect("Bob should have received the invite");
239///
240/// let event = room.event(&event_id, None).await?;
241///
242/// assert_decrypted_message_eq!(
243///     event,
244///     "It's a secret to everybody!",
245///     "The decrypted event should match the expected secret message"
246/// );
247/// # anyhow::Ok(()) };
248/// ```
249#[macro_export]
250macro_rules! assert_decrypted_message_eq {
251    ($event:expr, $expected:expr, $($msg:tt)*) => {{
252        assert_matches2::assert_let!($crate::deserialized_responses::TimelineEventKind::Decrypted(decrypted_event) = $event.kind);
253
254        let deserialized_event = decrypted_event
255            .event
256            .deserialize()
257            .expect("We should be able to deserialize the decrypted event");
258
259        assert_matches2::assert_let!(
260            $crate::ruma::events::AnyTimelineEvent::MessageLike(deserialized_event) = deserialized_event
261        );
262
263        let content =
264            deserialized_event.original_content().expect("The event should not have been redacted");
265        assert_matches2::assert_let!($crate::ruma::events::AnyMessageLikeEventContent::RoomMessage(content) = content);
266        assert_eq!(content.body(), $expected, $($msg)*);
267    }};
268    ($event:expr, $expected:expr) => {{
269        assert_decrypted_message_eq!($event, $expected, "The decrypted content did not match to the expected value");
270    }};
271}
272
273/// Given a [`TimelineEvent`], assert that the event is a decrypted state
274/// event, and that its content matches the given pattern via a let binding.
275///
276/// If more than one argument is provided, these will be used as an error
277/// message if the content does not match the provided pattern.
278///
279/// # Examples
280///
281/// ```no_run
282/// # async {
283/// # let client: matrix_sdk::Client = unreachable!();
284/// # let room_id: ruma::OwnedRoomId = unreachable!();
285/// # let event_id: ruma::OwnedEventId = unreachable!();
286/// use matrix_sdk::assert_let_decrypted_state_event_content;
287///
288/// let room =
289///     client.get_room(&room_id).expect("Bob should have received the invite");
290///
291/// let event = room.event(&event_id, None).await?;
292///
293/// assert_let_decrypted_state_event_content!(
294///     ruma::events::AnyStateEventContent::RoomTopic(
295///         ruma::events::room::topic::RoomTopicEventContent { topic, .. }
296///     ) = event
297/// );
298/// assert_eq!(topic, "Encrypted topic!");
299/// # anyhow::Ok(()) };
300/// ```
301#[macro_export]
302macro_rules! assert_let_decrypted_state_event_content {
303    ($pat:pat = $event:expr, $($msg:tt)*) => {
304        assert_matches2::assert_let!(
305            $crate::deserialized_responses::TimelineEventKind::Decrypted(decrypted_event) =
306                $event.kind,
307            "Event was not decrypted"
308        );
309
310        let deserialized_event = decrypted_event
311            .event
312            .deserialize_as_unchecked::<$crate::ruma::events::AnyStateEvent>()
313            .expect("We should be able to deserialize the decrypted event");
314
315        let content =
316            deserialized_event.original_content().expect("The event should not have been redacted");
317
318        assert_matches2::assert_let!($pat = content, $($msg)*);
319    };
320    ($pat:pat = $event:expr) => {
321        assert_let_decrypted_state_event_content!(
322            $pat = $event,
323            "The decrypted event did not match the expected value"
324        );
325    };
326}
327
328#[doc(hidden)]
329#[macro_export]
330macro_rules! assert_next_eq_with_timeout_impl {
331    ($stream:expr, $expected:expr, $timeout:expr) => {
332        let next_value = tokio::time::timeout(
333            $timeout,
334            $stream.next()
335        )
336        .await
337        .expect("We should be able to get the next value out of the stream by now")
338        .expect("The stream should have given us a new value instead of None");
339
340        assert_eq!(next_value, $expected);
341    };
342    ($stream:expr, $expected:expr, $timeout:expr, $($msg:tt)*) => {{
343        let next_value = tokio::time::timeout(
344            $timeout,
345            futures_util::StreamExt::next(&mut $stream)
346        )
347        .await
348        .expect("We should be able to get the next value out of the stream by now")
349        .expect("The stream should have given us a new value instead of None");
350
351        assert_eq!(next_value, $expected, $($msg)*);
352    }};
353}
354
355/// Like `assert_let`, but with the possibility to add an optional timeout.
356///
357/// If not provided, a timeout value of 100 milliseconds is used.
358#[macro_export]
359macro_rules! assert_let_timeout {
360    ($timeout:expr, $pat:pat = $future:expr) => {
361        assert_matches2::assert_let!(Ok($pat) = tokio::time::timeout($timeout, $future).await);
362    };
363
364    ($pat:pat = $future:expr) => {
365        assert_let_timeout!(std::time::Duration::from_millis(100), $pat = $future);
366    };
367}
matrix_sdk/test_utils/mod.rs

matrix_sdk/test_utils/
mod.rs
