Struct MatrixMockServer

pub struct MatrixMockServer { /* private fields */ }

Available on crate feature testing and non-WebAssembly only.

A wiremock MockServer along with useful methods to help mocking Matrix client-server API endpoints easily.

It implements mock endpoints, limiting the shared code as much as possible, so the mocks are still flexible to use as scoped/unscoped mounts, named, and so on.

It works like this:

• start by saying which endpoint you’d like to mock, e.g. Self::mock_room_send(). This returns a specialized MockEndpoint data structure, with its own impl. For this example, it’s MockEndpoint<RoomSendEndpoint>.
• configure the response on the endpoint-specific mock data structure. For instance, if you want the sending to result in a transient failure, call MockEndpoint::error500; if you want it to succeed and return the event $42, call MockEndpoint::ok(). It’s still possible to call MockEndpoint::respond_with(), as we do with wiremock MockBuilder, for maximum flexibility when the helpers aren’t sufficient.
• once the endpoint’s response is configured, for any mock builder, you get a MatrixMock; this is a plain wiremock::Mock with the server curried, so one doesn’t have to pass it around when calling MatrixMock::mount() or MatrixMock::mount_as_scoped(). As such, it mostly defers its implementations to wiremock::Mock under the hood.

Examples

use matrix_sdk::{ruma::{room_id, event_id}, test_utils::mocks::MatrixMockServer};
use serde_json::json;

// First create the mock server and client pair.
let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

// Let's say that our rooms are not encrypted.
mock_server.mock_room_state_encryption().plain().mount().await;

// Let us get a room where we will send an event.
let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

// Now we mock the endpoint so we can actually send the event.
let event_id = event_id!("$some_id");
let send_guard = mock_server
    .mock_room_send()
    .ok(event_id)
    .expect(1)
    .mount_as_scoped()
    .await;

// And we send it out.
let response = room.send_raw("m.room.message", json!({ "body": "Hello world" })).await?;

assert_eq!(
    event_id,
    response.event_id,
    "The event ID we mocked should match the one we received when we sent the event"
);

Implementations

impl MatrixMockServer

pub async fn new() -> Self

Create a new wiremock server specialized for Matrix usage.

pub fn from_server(server: MockServer) -> Self

Creates a new MatrixMockServer from a wiremock server.

pub fn client_builder(&self) -> MockClientBuilder

Creates a new MockClientBuilder configured to use this server, preconfigured with a session expected by the server endpoints.

pub fn server(&self) -> &MockServer

Return the underlying wiremock server.

pub async fn sync_room( &self, client: &Client, room_data: impl Into<AnyRoomBuilder>, ) -> Room

Overrides the sync/ endpoint with knowledge that the given invited/joined/knocked/left room exists, runs a sync and returns the given room.

Examples

use matrix_sdk::{ruma::{room_id, event_id}, test_utils::mocks::MatrixMockServer};
use matrix_sdk_test::LeftRoomBuilder;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

let left_room = mock_server
    .sync_room(&client, LeftRoomBuilder::new(room_id!("!room_id:localhost")))
    .await;

pub async fn sync_joined_room(&self, client: &Client, room_id: &RoomId) -> Room

Overrides the sync/ endpoint with knowledge that the given room exists in the joined state, runs a sync and returns the given room.

Examples

use matrix_sdk::{ruma::room_id, test_utils::mocks::MatrixMockServer};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

pub async fn verify_and_reset(&self)

Verify that the previous mocks expected number of requests match reality, and then cancels all active mocks.

Examples

use matrix_sdk::{ruma::{room_id, event_id}, test_utils::mocks::MatrixMockServer};
use serde_json::json;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_room_state_encryption().plain().mount().await;
let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;
mock_server.mock_room_send().ok(event_id!("$some_id")).mount().await;

// This will succeed.
let response = room.send_raw("m.room.message", json!({ "body": "Hello world" })).await?;

// Now we reset the mocks.
mock_server.verify_and_reset().await;

// And we can't send anymore.
let response = room
    .send_raw("m.room.message", json!({ "body": "Hello world" }))
    .await
    .expect_err("We removed the mock so sending should now fail");

impl MatrixMockServer

pub fn mock_sync(&self) -> MockEndpoint<'_, SyncEndpoint>

Mocks a sync endpoint.

Examples

use matrix_sdk::{ruma::room_id, test_utils::mocks::MatrixMockServer};
use matrix_sdk_test::JoinedRoomBuilder;

// First create the mock server and client pair.
let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;
let room_id = room_id!("!room_id:localhost");

// Let's emulate what `MatrixMockServer::sync_joined_room()` does.
mock_server
    .mock_sync()
    .ok_and_run(&client, |builder| {
        builder.add_joined_room(JoinedRoomBuilder::new(room_id));
    })
    .await;

let room = client
    .get_room(room_id)
    .expect("The room should be available after we mocked the sync");

pub fn mock_room_send(&self) -> MockEndpoint<'_, RoomSendEndpoint>

Creates a prebuilt mock for sending an event in a room.

Note: works with any room.

Examples

use matrix_sdk::{ruma::{room_id, event_id}, test_utils::mocks::MatrixMockServer};
use serde_json::json;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_room_state_encryption().plain().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

let event_id = event_id!("$some_id");
mock_server
    .mock_room_send()
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

let response = room.send_raw("m.room.message", json!({ "body": "Hello world" })).await?;

assert_eq!(
    event_id,
    response.event_id,
    "The event ID we mocked should match the one we received when we sent the event"
);

pub fn mock_room_send_state(&self) -> MockEndpoint<'_, RoomSendStateEndpoint>

Creates a prebuilt mock for sending a state event in a room.

Similar to: MatrixMockServer::mock_room_send

Note: works with any room. Note: works with any event type.

use matrix_sdk::{ruma::{room_id, event_id}, test_utils::mocks::MatrixMockServer};
use serde_json::json;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_room_state_encryption().plain().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

let event_id = event_id!("$some_id");
mock_server
    .mock_room_send_state()
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

let response_not_mocked = room.send_raw("m.room.create", json!({ "body": "Hello world" })).await;
// The `/send` endpoint should not be mocked by the server.
assert!(response_not_mocked.is_err());


let response = room.send_state_event_raw("m.room.message", "my_key", json!({ "body": "Hello world" })).await?;
// The `/state` endpoint should be mocked by the server.
assert_eq!(
    event_id,
    response.event_id,
    "The event ID we mocked should match the one we received when we sent the event"
);

pub fn mock_room_state_encryption( &self, ) -> MockEndpoint<'_, EncryptionStateEndpoint>

Creates a prebuilt mock for asking whether a room is encrypted or not.

Note: Applies to all rooms.

Examples

use matrix_sdk::{ruma::room_id, test_utils::mocks::MatrixMockServer};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_room_state_encryption().encrypted().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

assert!(
    room.is_encrypted().await?,
    "The room should be marked as encrypted."
);

pub fn mock_set_room_state_encryption( &self, ) -> MockEndpoint<'_, SetEncryptionStateEndpoint>

Creates a prebuilt mock for setting the room encryption state.

Note: Applies to all rooms.

Examples

use matrix_sdk::{
    ruma::{event_id, room_id},
    test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_room_state_encryption().plain().mount().await;
mock_server
    .mock_set_room_state_encryption()
    .ok(event_id!("$id"))
    .mock_once()
    .mount()
    .await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

room.enable_encryption()
    .await
    .expect("We should be able to enable encryption in the room");

pub fn mock_room_redact(&self) -> MockEndpoint<'_, RoomRedactEndpoint>

Creates a prebuilt mock for the room redact endpoint.

Examples

use matrix_sdk::{
    ruma::{event_id, room_id},
    test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;
let event_id = event_id!("$id");

mock_server.mock_room_redact().ok(event_id).mock_once().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

room.redact(event_id, None, None)
    .await
    .expect("We should be able to redact events in the room");

pub fn mock_room_event(&self) -> MockEndpoint<'_, RoomEventEndpoint>

Creates a prebuilt mock for retrieving an event with /room/…/event.

pub fn mock_room_messages(&self) -> MockEndpoint<'_, RoomMessagesEndpoint>

Create a prebuild mock for paginating room message with the /messages endpoint.

pub fn mock_upload(&self) -> MockEndpoint<'_, UploadEndpoint>

Create a prebuilt mock for uploading media.

pub fn mock_room_directory_resolve_alias( &self, ) -> MockEndpoint<'_, ResolveRoomAliasEndpoint>

Create a prebuilt mock for resolving room aliases.

Examples

use matrix_sdk::{
    ruma::{owned_room_id, room_alias_id},
    test_utils::mocks::MatrixMockServer,
};
let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server
    .mock_room_directory_resolve_alias()
    .ok("!a:b.c", Vec::new())
    .mock_once()
    .mount()
    .await;

let res = client
    .resolve_room_alias(room_alias_id!("#a:b.c"))
    .await
    .expect("We should be able to resolve the room alias");
assert_eq!(res.room_id, owned_room_id!("!a:b.c"));

pub fn mock_room_directory_create_room_alias( &self, ) -> MockEndpoint<'_, CreateRoomAliasEndpoint>

Create a prebuilt mock for publishing room aliases in the room directory.

Examples

use matrix_sdk::{
    ruma::{room_alias_id, room_id},
    test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server
    .mock_room_directory_create_room_alias()
    .ok()
    .mock_once()
    .mount()
    .await;

client
    .create_room_alias(room_alias_id!("#a:b.c"), room_id!("!a:b.c"))
    .await
    .expect("We should be able to create a room alias");

pub fn mock_room_directory_remove_room_alias( &self, ) -> MockEndpoint<'_, RemoveRoomAliasEndpoint>

Create a prebuilt mock for removing room aliases from the room directory.

Examples

use matrix_sdk::{
    ruma::room_alias_id, test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server
    .mock_room_directory_remove_room_alias()
    .ok()
    .mock_once()
    .mount()
    .await;

client
    .remove_room_alias(room_alias_id!("#a:b.c"))
    .await
    .expect("We should be able to remove the room alias");

pub fn mock_public_rooms(&self) -> MockEndpoint<'_, PublicRoomsEndpoint>

Create a prebuilt mock for listing public rooms.

Examples

tokio_test::block_on(async {
use js_int::uint;
use ruma::directory::PublicRoomsChunkInit;
use matrix_sdk::room_directory_search::RoomDirectorySearch;
use matrix_sdk::{
    ruma::{event_id, room_id},
    test_utils::mocks::MatrixMockServer,
};
let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;
let event_id = event_id!("$id");
let room_id = room_id!("!room_id:localhost");

let chunk = vec![PublicRoomsChunkInit {
    num_joined_members: uint!(0),
    room_id: room_id.to_owned(),
    world_readable: true,
    guest_can_join: true,
}.into()];

mock_server.mock_public_rooms().ok(chunk, None, None, Some(20)).mock_once().mount().await;
let mut room_directory_search = RoomDirectorySearch::new(client);

room_directory_search.search(Some("some-alias".to_owned()), 100, None)
    .await
    .expect("Room directory search failed");

let (results, _) = room_directory_search.results();
assert_eq!(results.len(), 1);
assert_eq!(results.get(0).unwrap().room_id, room_id.to_owned());

pub fn mock_room_directory_set_room_visibility( &self, ) -> MockEndpoint<'_, SetRoomVisibilityEndpoint>

Create a prebuilt mock for setting a room’s visibility in the room directory.

Examples

use matrix_sdk::{ruma::room_id, test_utils::mocks::MatrixMockServer};
use ruma::api::client::room::Visibility;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server
    .mock_room_directory_set_room_visibility()
    .ok()
    .mock_once()
    .mount()
    .await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

room.privacy_settings()
    .update_room_visibility(Visibility::Private)
    .await
    .expect("We should be able to update the room's visibility");

pub fn mock_room_directory_get_room_visibility( &self, ) -> MockEndpoint<'_, GetRoomVisibilityEndpoint>

Create a prebuilt mock for getting a room’s visibility in the room directory.

Examples

use matrix_sdk::{ruma::room_id, test_utils::mocks::MatrixMockServer};
use ruma::api::client::room::Visibility;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server
    .mock_room_directory_get_room_visibility()
    .ok(Visibility::Public)
    .mock_once()
    .mount()
    .await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

let visibility = room
    .privacy_settings()
    .get_room_visibility()
    .await
    .expect("We should be able to get the room's visibility");
assert_eq!(visibility, Visibility::Public);

pub fn mock_room_keys_version( &self, ) -> MockEndpoint<'_, RoomKeysVersionEndpoint>

Create a prebuilt mock for fetching information about key storage backups.

Examples

use matrix_sdk::test_utils::mocks::MatrixMockServer;

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_room_keys_version().exists().expect(1).mount().await;

let exists =
    client.encryption().backups().fetch_exists_on_server().await.unwrap();

assert!(exists);

pub fn mock_add_room_keys_version( &self, ) -> MockEndpoint<'_, AddRoomKeysVersionEndpoint>

Create a prebuilt mock for adding key storage backups via POST

pub fn mock_delete_room_keys_version( &self, ) -> MockEndpoint<'_, DeleteRoomKeysVersionEndpoint>

Create a prebuilt mock for adding key storage backups via POST

pub fn mock_get_members(&self) -> MockEndpoint<'_, GetRoomMembersEndpoint>

Create a prebuilt mock for getting the room members in a room.

Examples

use matrix_sdk::{
    ruma::{event_id, room_id},
    test_utils::mocks::MatrixMockServer,
};
use matrix_sdk_base::RoomMemberships;
use matrix_sdk_test::event_factory::EventFactory;
use ruma::{
    events::room::member::{MembershipState, RoomMemberEventContent},
    user_id,
};
let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;
let event_id = event_id!("$id");
let room_id = room_id!("!room_id:localhost");

let f = EventFactory::new().room(room_id);
let alice_user_id = user_id!("@alice:b.c");
let alice_knock_event = f
    .event(RoomMemberEventContent::new(MembershipState::Knock))
    .event_id(event_id)
    .sender(alice_user_id)
    .state_key(alice_user_id)
    .into_raw_timeline()
    .cast();

mock_server
    .mock_get_members()
    .ok(vec![alice_knock_event])
    .mock_once()
    .mount()
    .await;
let room = mock_server.sync_joined_room(&client, room_id).await;

let members = room.members(RoomMemberships::all()).await.unwrap();
assert_eq!(members.len(), 1);

pub fn mock_invite_user_by_id(&self) -> MockEndpoint<'_, InviteUserByIdEndpoint>

Creates a prebuilt mock for inviting a user to a room by its id.

Examples

tokio_test::block_on(async {
use matrix_sdk::{
    ruma::room_id,
    test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_invite_user_by_id().ok().mock_once().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

room.invite_user_by_id(user_id!("@alice:localhost")).await.unwrap();

pub fn mock_kick_user(&self) -> MockEndpoint<'_, KickUserEndpoint>

Creates a prebuilt mock for kicking a user from a room.

Examples

tokio_test::block_on(async {
use matrix_sdk::{
    ruma::room_id,
    test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_kick_user().ok().mock_once().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

room.kick_user(user_id!("@alice:localhost"), None).await.unwrap();

pub fn mock_ban_user(&self) -> MockEndpoint<'_, BanUserEndpoint>

Creates a prebuilt mock for banning a user from a room.

Examples

tokio_test::block_on(async {
use matrix_sdk::{
    ruma::room_id,
    test_utils::mocks::MatrixMockServer,
};

let mock_server = MatrixMockServer::new().await;
let client = mock_server.client_builder().build().await;

mock_server.mock_ban_user().ok().mock_once().mount().await;

let room = mock_server
    .sync_joined_room(&client, room_id!("!room_id:localhost"))
    .await;

room.ban_user(user_id!("@alice:localhost"), None).await.unwrap();

pub fn mock_versions(&self) -> MockEndpoint<'_, VersionsEndpoint>

Creates a prebuilt mock for the /_matrix/client/versions endpoint.

pub fn mock_room_summary(&self) -> MockEndpoint<'_, RoomSummaryEndpoint>

Creates a prebuilt mock for the room summary endpoint MSC3266.

pub fn mock_set_room_pinned_events( &self, ) -> MockEndpoint<'_, SetRoomPinnedEventsEndpoint>

Creates a prebuilt mock for the endpoint used to set a room’s pinned events.