Struct MockEndpoint

pub struct MockEndpoint<'a, T> { /* private fields */ }

Available on crate feature testing and non-WebAssembly only.

Generic mocked endpoint, with useful common helpers.

Implementations

impl<'a, T> MockEndpoint<'a, T>

pub fn respond_with<R: Respond + 'static>(self, func: R) -> MatrixMock<'a>

Specify how to respond to a query (viz., like MockBuilder::respond_with does), when other predefined responses aren’t sufficient.

Examples

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

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()
    .respond_with(
        ResponseTemplate::new(429)
            .insert_header("Retry-After", "100")
            .set_body_json(json!({
                "errcode": "M_LIMIT_EXCEEDED",
                "custom_field": "with custom data",
    })))
    .expect(1)
    .mount()
    .await;

room
    .send_raw("m.room.message", json!({ "body": "Hello world" }))
    .await
    .expect_err("The sending of the event should fail");

pub fn error500(self) -> MatrixMock<'a>

Returns a send endpoint that emulates a transient failure, i.e responds with error 500.

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()
    .error500()
    .expect(1)
    .mount()
    .await;

room
    .send_raw("m.room.message", json!({ "body": "Hello world" }))
    .await.expect_err("The sending of the event should have failed");

pub fn error_too_large(self) -> MatrixMock<'a>

Returns an endpoint that emulates a permanent failure error (e.g. event is too large).

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()
    .error_too_large()
    .expect(1)
    .mount()
    .await;

room
    .send_raw("m.room.message", json!({ "body": "Hello world" }))
    .await.expect_err("The sending of the event should have failed");

impl<'a> MockEndpoint<'a, RoomSendEndpoint>

pub fn body_matches_partial_json(self, body: Value) -> Self

Ensures that the body of the request is a superset of the provided body parameter.

Examples

use matrix_sdk::{
    ruma::{room_id, event_id, events::room::message::RoomMessageEventContent},
    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()
    .body_matches_partial_json(json!({
        "body": "Hello world",
    }))
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

let content = RoomMessageEventContent::text_plain("Hello world");
let response = room.send(content).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 for_type(self, event_type: MessageLikeEventType) -> Self

Ensures that the send endpoint request uses a specific event type.

Examples

see also MatrixMockServer::mock_room_send for more context.

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()
    .for_type("m.room.message".into())
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

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

let response = room.send_raw("m.room.message", json!({ "body": "Hello world" })).await?;
// The `m.room.message` event type 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 with_delay(self, delay: Duration) -> Self

Ensures the event was sent as a delayed event.

Note: works with any room.

Examples

see also MatrixMockServer::mock_room_send for more context.

use matrix_sdk::{
    ruma::{
        api::client::delayed_events::{delayed_message_event, DelayParameters},
        events::{message::MessageEventContent, AnyMessageLikeEventContent},
        room_id,
        time::Duration,
        TransactionId,
    },
    test_utils::mocks::MatrixMockServer,
};
use serde_json::json;
use wiremock::ResponseTemplate;

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()
    .with_delay(Duration::from_millis(500))
    .respond_with(ResponseTemplate::new(200).set_body_json(json!({"delay_id":"$some_id"})))
    .mock_once()
    .mount()
    .await;

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

// A non delayed event should not be mocked by the server.
assert!(response_not_mocked.is_err());

let r = delayed_message_event::unstable::Request::new(
    room.room_id().to_owned(),
    TransactionId::new(),
    DelayParameters::Timeout { timeout: Duration::from_millis(500) },
    &AnyMessageLikeEventContent::Message(MessageEventContent::plain("hello world")),
)
.unwrap();

let response = room.client().send(r).await.unwrap();
// The delayed `m.room.message` event type should be mocked by the server.
assert_eq!("$some_id", response.delay_id);

pub fn ok(self, returned_event_id: impl Into<OwnedEventId>) -> MatrixMock<'a>

Returns a send endpoint that emulates success, i.e. the event has been sent with the given event id.

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");
let send_guard = mock_server
    .mock_room_send()
    .ok(event_id)
    .expect(1)
    .mount_as_scoped()
    .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"
);

impl<'a> MockEndpoint<'a, RoomSendStateEndpoint>

pub fn body_matches_partial_json(self, body: Value) -> Self

Ensures that the body of the request is a superset of the provided body parameter.

Examples

use matrix_sdk::{
    ruma::{room_id, event_id, events::room::power_levels::RoomPowerLevelsEventContent},
    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()
    .body_matches_partial_json(json!({
        "redact": 51,
    }))
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

let mut content = RoomPowerLevelsEventContent::new();
// Update the power level to a non default value.
// Otherwise it will be skipped from serialization.
content.redact = 51.into();

let response = room.send_state_event(content).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 for_type(self, event_type: StateEventType) -> Self

Ensures that the send endpoint request uses a specific event type.

Note: works with any room.

Examples

see also MatrixMockServer::mock_room_send for more context.

use matrix_sdk::{
    ruma::{
        event_id,
        events::room::{
            create::RoomCreateEventContent, power_levels::RoomPowerLevelsEventContent,
        },
        events::StateEventType,
        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;

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()
    .for_type(StateEventType::RoomPowerLevels)
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

let response_not_mocked = room.send_state_event(RoomCreateEventContent::new_v11()).await;
// The `m.room.reaction` event type should not be mocked by the server.
assert!(response_not_mocked.is_err());

let response = room.send_state_event(RoomPowerLevelsEventContent::new()).await?;
// The `m.room.message` event type 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 with_delay(self, delay: Duration) -> Self

Ensures the event was sent as a delayed event.

Note: works with any room.

Examples

see also MatrixMockServer::mock_room_send for more context.

use matrix_sdk::{
    ruma::{
        api::client::delayed_events::{delayed_state_event, DelayParameters},
        events::{room::create::RoomCreateEventContent, AnyStateEventContent},
        room_id,
        time::Duration,
    },
    test_utils::mocks::MatrixMockServer,
};
use wiremock::ResponseTemplate;
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_state()
    .with_delay(Duration::from_millis(500))
    .respond_with(ResponseTemplate::new(200).set_body_json(json!({"delay_id":"$some_id"})))
    .mock_once()
    .mount()
    .await;

let response_not_mocked = room.send_state_event(RoomCreateEventContent::new_v11()).await;
// A non delayed event should not be mocked by the server.
assert!(response_not_mocked.is_err());

let r = delayed_state_event::unstable::Request::new(
    room.room_id().to_owned(),
    "".to_owned(),
    DelayParameters::Timeout { timeout: Duration::from_millis(500) },
    &AnyStateEventContent::RoomCreate(RoomCreateEventContent::new_v11()),
)
.unwrap();
let response = room.client().send(r).await.unwrap();
// The delayed `m.room.message` event type should be mocked by the server.
assert_eq!("$some_id", response.delay_id);

pub fn for_key(self, state_key: String) -> Self

use matrix_sdk::{
    ruma::{
        event_id,
        events::{call::member::CallMemberEventContent, AnyStateEventContent},
        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;

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()
    .for_key("my_key".to_owned())
    .ok(event_id)
    .expect(1)
    .mount()
    .await;

let response_not_mocked = room
    .send_state_event_for_key(
        "",
        AnyStateEventContent::CallMember(CallMemberEventContent::new_empty(None)),
    )
    .await;
// The `m.room.reaction` event type should not be mocked by the server.
assert!(response_not_mocked.is_err());

let response = room
    .send_state_event_for_key(
        "my_key",
        AnyStateEventContent::CallMember(CallMemberEventContent::new_empty(None)),
    )
    .await
    .unwrap();

// The `m.room.message` event type 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 ok(self, returned_event_id: impl Into<OwnedEventId>) -> MatrixMock<'a>

Returns a send endpoint that emulates success, i.e. the event has been sent with the given event id.

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");
let send_guard = mock_server
    .mock_room_send_state()
    .ok(event_id)
    .expect(1)
    .mount_as_scoped()
    .await;

let response = room.send_state_event_raw("m.room.message", "my_key", 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"
);

impl MockEndpoint<'_, SyncEndpoint>

pub async fn ok_and_run<F: FnOnce(&mut SyncResponseBuilder)>( self, client: &Client, func: F, )

Temporarily mocks the sync with the given endpoint and runs a client sync with it.

After calling this function, the sync endpoint isn’t mocked anymore.

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");

impl<'a> MockEndpoint<'a, EncryptionStateEndpoint>

pub fn encrypted(self) -> MatrixMock<'a>

Marks the room as encrypted.

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 plain(self) -> MatrixMock<'a>

Marks the room as not encrypted.

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().plain().mount().await;

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

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

impl<'a> MockEndpoint<'a, SetEncryptionStateEndpoint>

pub fn ok(self, returned_event_id: impl Into<OwnedEventId>) -> MatrixMock<'a>

Returns a mock for a successful setting of the encryption state event.

impl<'a> MockEndpoint<'a, RoomRedactEndpoint>

pub fn ok(self, returned_event_id: impl Into<OwnedEventId>) -> MatrixMock<'a>

Returns a redact endpoint that emulates success, i.e. the redaction event has been sent with the given event id.

impl<'a> MockEndpoint<'a, RoomEventEndpoint>

pub fn room(self, room: impl Into<OwnedRoomId>) -> Self

Limits the scope of this mock to a specific room.

pub fn match_event_id(self) -> Self

Whether the mock checks for the event id from the event.

pub fn ok(self, event: TimelineEvent) -> MatrixMock<'a>

Returns a redact endpoint that emulates success, i.e. the redaction event has been sent with the given event id.

impl<'a> MockEndpoint<'a, RoomMessagesEndpoint>

A prebuilt mock for getting a room messages in a room.

pub fn limit(self, limit: u32) -> Self

Expects an optional limit to be set on the request.

pub fn from(self, from: &str) -> Self

Expects an optional from to be set on the request.

pub fn ok(self, response: RoomMessagesResponseTemplate) -> MatrixMock<'a>

Returns a messages endpoint that emulates success, i.e. the messages provided as response could be retrieved.

Note: pass chunk in the correct order: topological for forward pagination, reverse topological for backwards pagination.

impl<'a> MockEndpoint<'a, UploadEndpoint>

pub fn expect_mime_type(self, content_type: &str) -> Self

Expect that the content type matches what’s given here.

pub fn ok(self, mxc_id: &MxcUri) -> MatrixMock<'a>

Returns a redact endpoint that emulates success, i.e. the redaction event has been sent with the given event id.

impl<'a> MockEndpoint<'a, ResolveRoomAliasEndpoint>

pub fn for_alias(self, alias: impl Into<String>) -> Self

Sets up the endpoint to only intercept requests for the given room alias.

pub fn ok(self, room_id: &str, servers: Vec<String>) -> MatrixMock<'a>

Returns a data endpoint with a resolved room alias.

pub fn not_found(self) -> MatrixMock<'a>

Returns a data endpoint for a room alias that does not exit.

impl<'a> MockEndpoint<'a, CreateRoomAliasEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns a data endpoint for creating a room alias.

impl<'a> MockEndpoint<'a, RemoveRoomAliasEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns a data endpoint for removing a room alias.

impl<'a> MockEndpoint<'a, PublicRoomsEndpoint>

pub fn ok( self, chunk: Vec<PublicRoomsChunk>, next_batch: Option<String>, prev_batch: Option<String>, total_room_count_estimate: Option<u64>, ) -> MatrixMock<'a>

Returns a data endpoint for paginating the public room list.

pub fn ok_with_via_params( self, server_map: BTreeMap<OwnedServerName, Vec<PublicRoomsChunk>>, ) -> MatrixMock<'a>

Returns a data endpoint for paginating the public room list with several via params.

Each via param must be in the server_map parameter, otherwise it’ll fail.

impl<'a> MockEndpoint<'a, GetRoomVisibilityEndpoint>

pub fn ok(self, visibility: Visibility) -> MatrixMock<'a>

Returns an endpoint that get the room’s public visibility.

impl<'a> MockEndpoint<'a, SetRoomVisibilityEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns an endpoint that updates the room’s visibility.

impl<'a> MockEndpoint<'a, RoomKeysVersionEndpoint>

pub fn exists(self) -> MatrixMock<'a>

Returns an endpoint that says there is a single room keys backup

pub fn none(self) -> MatrixMock<'a>

Returns an endpoint that says there is no room keys backup

pub fn error429(self) -> MatrixMock<'a>

Returns an endpoint that 429 errors when we get it

pub fn error404(self) -> MatrixMock<'a>

Returns an endpoint that 404 errors when we get it

impl<'a> MockEndpoint<'a, AddRoomKeysVersionEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns an endpoint that may be used to add room key backups

impl<'a> MockEndpoint<'a, DeleteRoomKeysVersionEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns an endpoint that allows deleting room key backups

impl<'a> MockEndpoint<'a, GetRoomMembersEndpoint>

pub fn ok(self, members: Vec<Raw<RoomMemberEvent>>) -> MatrixMock<'a>

Returns a successful get members request with a list of members.

impl<'a> MockEndpoint<'a, InviteUserByIdEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns a successful invite user by id request.

impl<'a> MockEndpoint<'a, KickUserEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns a successful kick user request.

impl<'a> MockEndpoint<'a, BanUserEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns a successful ban user request.

impl<'a> MockEndpoint<'a, VersionsEndpoint>

pub fn ok(self) -> MatrixMock<'a>

Returns a successful /_matrix/client/versions request.

The response will return some commonly supported versions.

impl<'a> MockEndpoint<'a, RoomSummaryEndpoint>

pub fn ok(self, room_id: &RoomId) -> MatrixMock<'a>

Returns a successful response with some default data for the given room id.

impl<'a> MockEndpoint<'a, SetRoomPinnedEventsEndpoint>

pub fn ok(self, event_id: OwnedEventId) -> MatrixMock<'a>

Returns a successful response with a given event id. id.

pub fn unauthorized(self) -> MatrixMock<'a>

Returns an error response with a generic error code indicating the client is not authorized to set pinned events.