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 fn oauth(&self) -> OAuthMockServer<'_>

Get an OAuthMockServer that uses the same mock server as this one.

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.latest_encryption_state().await?.is_encrypted(),
    "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.

pub fn mock_who_am_i(&self) -> MockEndpoint<'_, WhoAmIEndpoint>

Creates a prebuilt mock for the endpoint used to get information about the owner of the given access token.

If no access token is provided, the access token to match is "1234", which matches the default value in the mock data.

pub fn mock_upload_keys(&self) -> MockEndpoint<'_, UploadKeysEndpoint>

Creates a prebuilt mock for the endpoint used to publish end-to-end encryption keys.

pub fn mock_query_keys(&self) -> MockEndpoint<'_, QueryKeysEndpoint>

Creates a prebuilt mock for the endpoint used to query end-to-end encryption keys.

pub fn mock_well_known(&self) -> MockEndpoint<'_, WellKnownEndpoint>

Creates a prebuilt mock for the endpoint used to discover the URL of a homeserver.

pub fn mock_upload_cross_signing_keys( &self, ) -> MockEndpoint<'_, UploadCrossSigningKeysEndpoint>

Creates a prebuilt mock for the endpoint used to publish cross-signing keys.

pub fn mock_upload_cross_signing_signatures( &self, ) -> MockEndpoint<'_, UploadCrossSigningSignaturesEndpoint>

Creates a prebuilt mock for the endpoint used to publish cross-signing signatures.

pub fn mock_room_leave(&self) -> MockEndpoint<'_, RoomLeaveEndpoint>

Creates a prebuilt mock for the endpoint used to leave a room.