Skip to main content

Module testkit

Module testkit 

Source
Available on crate feature testkit only.
Expand description

Backend conformance suite for ChatBackend implementations.

Gated behind feature = "testkit". Each test is a pub async fn generic over ConformanceBackend, drives the backend through this crate’s method handlers, and states its oracle (draft or RFC text) in its rustdoc. A backend crate runs the whole suite with one ConformanceBackend impl and one macro line in an integration test:

ⓘ
// tests/backend_conformance.rs
jmap_chat_server::chat_backend_conformance!(MyBackend::new_for_test);

chat_backend_conformance! emits one #[test] per suite test, each calling the given constructor for a fresh, empty backend and running the test through run, so the calling crate needs no tokio macros.

§What the suite assumes

Every test runs in one account, a1, which it registers with ConformanceBackend::add_account; a few register further accounts. Requests act as the owner of the account (ConformanceBackend::caller). Fixtures are hand-written JSON stored with ConformanceBackend::seed.

§Capability-gated tests

A test whose assertion holds only for some backend configurations returns early, and so passes, when the backend does not have that configuration:

  • The replyCount / unreadReplyCount tests check ChatLimits::supports_threads from ChatSettings::limits; one test runs only when it is false, the others only when it is true. Run the macro once per configuration to cover both.
  • The exact Chat.unreadCount tests run only when ChatSettings::maintains_unread_count is false, where this crate keeps the count exact. draft-atwood-jmap-chat-00 §Chat unreadCount lets a backend that keeps the count itself update it “some time after the change that affects it” and “report a server-defined maximum”.
  • The outbound-event test runs only when ConformanceBackend::take_outbound_events returns Some.

Traits§

ConformanceBackend
The test seam a ChatBackend implements to run the conformance suite.

Functions§

absent_last_read_counts_every_message
aa01dd7 L635: candidates are “all Messages in the Chat if lastReadMessageId is absent.” Only Messages “in this Chat” count, so h has 1.
anchor_absent_from_results_is_anchor_not_found
RFC 8620 §5.5: “If the anchor is not found, the call is rejected with an “anchorNotFound” error.“
anchor_arguments_of_wrong_type_are_invalid_arguments
RFC 8620 §5.5 argument types: “anchor: “Id|null”“ and “anchorOffset: “Int” (default: 0)“; RFC 8620 §3.6.2 ““invalidArguments”: One of the arguments is of the wrong type or is otherwise invalid“.
anchor_offset_before_start_clamps_to_zero
RFC 8620 §5.5: “If the resulting index is now negative, it is clamped to 0.”
anchor_offset_without_anchor_is_ignored
RFC 8620 §5.5: “If no “anchor” is supplied, any “anchorOffset” argument MUST be ignored.“
anchor_overrides_position
RFC 8620 §5.5: “If an “anchor” is specified, any position argument supplied by the client MUST be ignored.“
anchor_with_negative_offset_starts_before_anchor
RFC 8620 §5.5 anchorOffset: “This MAY be negative. For example, “-1” means the Foo immediately preceding the anchor is the first result in the list returned“.
anchor_with_positive_offset_starts_after_anchor
RFC 8620 §5.5: “If an “anchor” argument is given, the anchor is looked for in the results after filtering and sorting. If found, the “anchorOffset” is then added to its index. … This index is now used exactly as though it were supplied as the “position” argument.“
anchor_without_offset_starts_at_anchor
RFC 8620 §5.5 anchorOffset: “(default: 0)”. Without an offset the anchor itself is the first result.
chat_destroy_destroys_its_read_position
L993: the server “destroys it when the Chat is destroyed”; RFC 8620 §5.1 makes ReadPosition/changes report it.
chat_muted_null_resets_to_false
Oracle: draft-atwood-jmap-chat-00 Chat muted: “When true, push notifications for this chat are suppressed. […] Default: false.”
chat_pinned_message_ids_null_resets_to_empty
Oracle: draft-atwood-jmap-chat-00 Chat pinnedMessageIds: “Ordered list of pinned Message ids, most-recently-pinned first. […] Empty by default.”
chat_query_applies_filter_operators
RFC 8620 §5.5 FilterOperator: “AND: All of the conditions must match for the filter to match. OR: At least one of the conditions must match for the filter to match. NOT: None of the conditions must match for the filter to match.”
chat_query_filters_kind_and_muted
L1139 (jmap-chat-spec 33702a5) §Chat/query: “Filter properties: kind (String), muted (Boolean).”
chat_receipt_sharing_null_removes_override
Oracle: draft-atwood-jmap-chat-00 Chat receiptSharing (line 645-646 at spec 29e9a41): “(Boolean, optional) Per-Chat override of the account-level PresenceStatus.receiptSharing preference … When absent, the account-level preference applies.” The property has no default, so null removes the override and /get omits it (bd:JMAP-w9ox.2).
chat_receive_typing_indicators_null_resets_to_true
Oracle: draft-atwood-jmap-chat-00 Chat receiveTypingIndicators: “Default: true.”
client_last_read_at_is_rejected
L1004 lastReadAt is server-set: a client write is invalidProperties (RFC 8620 §5.3) and the record is unchanged.
compliance_11_1_unread_count_from_read_position
Compliance §11.1: “Send 5 messages. Set ReadPosition to message 3. Call Chat/get. Verify unreadCount is 2 (messages 4 and 5).”
compliance_11_1_with_assigned_ids
Compliance §11.1 with server-assigned ids: “Send 5 messages. Set ReadPosition to message 3. Call Chat/get. Verify unreadCount is 2 (messages 4 and 5).” The count holds only if, per L675, “Message IDs are ULIDs […] lexicographically ordered by time”, including for messages sent within the same millisecond (bd:JMAP-nls1).
concurrent_redemptions_increment_exactly_once
draft-atwood-jmap-chat-00 §Space/join (jmap-chat-spec 77c3474 L1416): “The uses increment and membership insertion SHOULD be performed within a single atomic operation”, which this crate requires by choice. Concurrent redemptions are serialized: exactly one succeeds, uses is incremented exactly once and the member appears exactly once.
contact_blocked_null_resets_to_false
Oracle: draft-atwood-jmap-chat-00 ChatContact blocked: “When true, messages from this ChatContact are silently dropped by this mailbox […] Default: false.”
contact_create_by_identity_assigns_id
draft-atwood-jmap-chat-00 §ChatContact/set: “create accepts only identity, which is required; the server assigns id and sets the other server-set properties.”
contact_create_existing_identity_already_exists
draft-atwood-jmap-chat-00 §ChatContact/set: “If a ChatContact with that identity already exists, the server MUST reject the create with a SetError of type alreadyExists, including the existing ChatContact’s id in the existingId field ({{RFC8620}} Section 5.3).”
contact_create_other_properties_invalid_properties
draft-atwood-jmap-chat-00 §ChatContact/set: “create accepts only identity”. Any other property in a create is rejected with an RFC 8620 §5.3 invalidProperties SetError naming it, and no ChatContact is recorded.
contact_create_without_identity_invalid_properties
draft-atwood-jmap-chat-00 §ChatContact/set: “create accepts only identity, which is required”. A create without identity is an invalid record (RFC 8620 §5.3 invalidProperties).
contact_query_filters_blocked_and_presence
L1064 (jmap-chat-spec 33702a5) §ChatContact/query: “Filter properties: blocked (Boolean), presence (String), identity (String; …).”
contact_query_identity_filter_matches_octet_for_octet
draft-atwood-jmap-chat-00 §ChatContact/query: “Filter properties: blocked (Boolean), presence (String), identity (String; matches the ChatContact whose identity equals the value octet for octet).” The case-variant contact shows the match is octet-exact.
contact_query_sort_last_active_at_absent_sorts_last
draft-atwood-jmap-chat-00 §ChatContact/query: “When sorting by lastActiveAt, ChatContacts for which the field is absent sort last.” in both directions.
counts_absent_without_supports_threads
L639 / L642 (jmap-chat-spec 91672c9) “Present only when supportsThreads is true”: with supportsThreads: false neither count is returned.
create_message_stores_and_reports_one_new_message
Creates one Message and checks the stored Message, the state change and the single NewMessage event against the spec.
create_then_get
Oracle: created objects are retrievable by id.
emoji_query_changes_applies_space_id_filter
RFC 8620 §5.6: CustomEmoji/queryChanges with the query’s spaceId filter adds only emoji that the query matches.
emoji_query_filters_space_id
L1482 (jmap-chat-spec 33702a5) §CustomEmoji/query: “Filter properties: spaceId (String, optional — if absent returns all emoji accessible to the account including server-global).”
emoji_query_wrongly_typed_args_do_not_echo_value
RFC 8620 §5.5 types limit as “UnsignedInt|null” and position as “Int”; wrong types are invalidArguments (§3.6.2). The description names only the JSON type: §3.6.1 reserves it for “unstructured English text suitable for displaying to a developer”, so the client-supplied value is never echoed (bd JMAP-zegc). CustomEmoji/query parses these arguments itself rather than through jmap_server::handle_query.
exhausted_invite_is_refused_without_any_write
draft-atwood-jmap-chat-00 §Space/join: “… so that concurrent redemptions cannot exceed maxUses”: the backend re-checks maxUses itself rather than trusting the handler’s earlier read, and the refusal writes nothing.
expires_after_read_seconds_counts_from_read_at
L753 (jmap-chat-spec 77c3474), §Message expiresAfterReadSeconds: “the receiving server SHOULD permanently hard-delete this message (row removal, not tombstone) this many seconds after setting readAt.”
expiry_records_chat_unread_count_change
jmap-chat-spec aa01dd7 L635, §Chat unreadCount: “Candidates are the Messages whose id ULID is lexicographically greater than ReadPosition.lastReadMessageId, or all Messages in the Chat if lastReadMessageId is absent.” An expired Message lowers that count, and RFC 8620 §5.1 (“If the data changes, this string MUST change”) then requires the Chat state to move (bd:JMAP-y3f2.18).
extreme_position_and_limit_saturate
RFC 8620 §1.3 bounds Int to “-2^53+1 <= value <= 2^53-1” and UnsignedInt to “0 <= value <= 2^53-1”. §5.5 position: “the negative value MUST be added to the total number of results given the filter, and if still negative, it’s clamped to “0”“, so the most negative legal position starts at index 0, and the largest legal limit returns all five results (bd:JMAP-uqhn.2).
invalid_read_at_patch_is_rejected_without_burning
Oracle: draft-atwood-jmap-chat-00 (jmap-chat-spec 77c3474 L750) §Message burnOnRead: “When true, the receiving server SHOULD permanently hard-delete this message (row removal, not tombstone) immediately after setting readAt.” This crate performs the recommended deletion, so the readAt write is never stored without it.
is_contact_blocked_reads_chat_contact_blocked_field
Oracle: is_contact_blocked reads ChatContact.blocked from the store. The backend’s predicate is exercised directly, mirroring the way a consumer’s transport layer would consult it before a fan-out.
is_contact_blocked_reads_only_the_owner_list
Oracle: draft-atwood-jmap-chat-00 §Blocked Contacts (L1698): “Typing and presence push events whose sending or referenced ChatContact has blocked: true on the receiving owner’s contact list are similarly dropped”, and §ChatContact id (L426): “It identifies the ChatContact only on this server”. Two accounts each hold a ChatContact for the other; only the recipient’s own list decides, and a contact id is never resolved in another account’s list.
join_adds_member_and_counts_use_together
draft-atwood-jmap-chat-00 §Space/join: “… atomically increment uses and add the caller to the Space’s member list”: one join produces both effects, each recorded as a change.
largest_position_is_empty_page_not_error
RFC 8620 §5.5 position: “If the index is greater than or equal to the total number of objects in the results list, then the “ids” array in the response will be empty, but this is not an error.“
message_actions_null_resets_to_empty
Oracle: draft-atwood-jmap-chat-00 Message actions: “Out-of-band action invitations associated with this message. Empty by default.”
message_broadcast_mentions_null_resets_to_empty
Oracle: draft-atwood-jmap-chat-00 Message broadcastMentions: “Structured broadcast-scope mention annotations […]. Empty by default.”
message_destroy_advances_chat_state
Destroying an unread Message lowers the Chat’s unreadCount (L629), so Chat/changes reports that Chat (RFC 8620 §5.2).
message_expiry_seconds_deletes_messages_older_than_policy
L581 (jmap-chat-spec 91672c9), §Chat messageExpirySeconds: “When set and non-zero, messages in this chat older than this many seconds are deleted by this mailbox.” L654, §Message receivedAt: “Authoritative for ordering and expiry calculations.”
message_mentions_null_resets_to_empty
Oracle: draft-atwood-jmap-chat-00 Message mentions: “Structured per-user @mention annotations. Empty by default.”
message_query_changes_refuses_text_filter
L1279 (jmap-chat-spec 33702a5) §Message/query text: “Servers that do not support full-text search MUST return unsupportedFilter.”
message_query_changes_requires_chat_id_or_has_mention
L1269: “Servers MUST return an unsupportedFilter error for any request that omits chatId without also including hasMention: true” applies to Message/queryChanges too.
message_query_filters_has_attachment_both_ways
L1288 (jmap-chat-spec 33702a5) hasAttachment: “Filter to messages with or without attachments.”
message_query_filters_topic_id
L1285 (jmap-chat-spec 33702a5) topicId: “Return only messages whose topicId equals this value.”
message_query_has_mention_false_excludes_mentions
L1291 (jmap-chat-spec 33702a5) hasMention: “Filter to messages that mention the owner: the accountId appears in mentions, OR …”
message_reactions_null_resets_to_empty
Oracle: draft-atwood-jmap-chat-00 Message reactions: “Emoji reactions, keyed by senderReactionId. […] Empty object by default.”
mute_until_clears_muted_and_mute_until
L559 (jmap-chat-spec 91672c9), §Chat muteUntil: “Muting expires at this time. Servers SHOULD clear muted and muteUntil automatically when the time passes.”
path_depth_counts_toward_nesting_cap
Oracle: bd:JMAP-wlip.1 caps /set update nesting at 32 levels and rejects deeper patches as RFC 8620 §5.3 “invalidPatch”, leaving the record unchanged. Because §5.3 makes keys “a path in JSON Pointer format”, the path itself reaches into the object, so its segments count toward the cap. Test vector: a 21-segment path into an existing 21-level value, setting another 21-level value, would store 43 levels; each repeat could add 21 more.
path_key_updates_nested_member
Oracle: RFC 8620 §5.3: “The keys are a path in JSON Pointer format [RFC6901], with an implicit leading “/”“. The key deliveryReceipts/u2 therefore adds member u2 of the deliveryReceipts object, keeping u1, rather than creating a property literally named deliveryReceipts/u2.
path_through_absent_parent_is_invalid_patch
Oracle: RFC 8620 §5.3: “All parts prior to the last (i.e., the value after the final slash) MUST already exist on the object being patched.” and “if there is any violation, the update MUST be rejected with an “invalidPatch” error“. A fresh Message has no deliveryReceipts, so deliveryReceipts/u1 is rejected and the stored Message is unchanged.
prefix_conflict_is_invalid_patch
Oracle: RFC 8620 §5.3: “There MUST NOT be two patches in the PatchObject where the pointer of one is the prefix of the pointer of the other, e.g., “alerts/1/offset” and “alerts”.“ and “if there is any violation, the update MUST be rejected with an “invalidPatch” error“. The stored Message is unchanged.
presence_expires_at_resets_status
L941-942 (jmap-chat-spec 91672c9), §PresenceStatus expiresAt: “If set, the server SHOULD clear statusText and statusEmoji (setting them to null) at this time, and SHOULD reset presence to "online".”
presence_null_resets_to_online
Oracle: draft-atwood-jmap-chat-00 PresenceStatus presence: “One of "online", "away", "busy", "invisible", or "offline". Default is "online".”
presence_receipt_sharing_null_resets_to_true
Oracle: draft-atwood-jmap-chat-00 PresenceStatus receiptSharing: “When false, this account does not send read receipts to peers. […] Default: true.”
read_burn_on_read_message_is_deleted
L750 (jmap-chat-spec 77c3474), §Message burnOnRead: “the receiving server SHOULD permanently hard-delete this message (row removal, not tombstone) immediately after setting readAt.”
read_position_set_advances_chat_state
L1434 “updates Chat.unreadCount for the affected Chat” changes Chat data, so (RFC 8620 §5.1) the Chat state moves and (§5.2) Chat/changes lists only the affected Chat.
read_position_set_updates_last_read_at
L1434: “The server sets lastReadAt to the current time”.
read_position_update_lists_thread_root_updated
RFC 8620 §5.1: “If the data changes, this string MUST change.” Moving lastReadMessageId from A to C (L641-642, ids ordered per L591) marks reply C to ROOT read, so ROOT’s unreadReplyCount drops from 1 to 0 and ROOT is listed as updated. B also crosses the read mark, but its parent A has a threadRootId, carries no unreadReplyCount, and is not listed.
read_rules_spare_the_senders_own_copy
L660 and L663 (jmap-chat-spec 91672c9), both rules: “Applies only to the receiving mailbox; the sender’s own copy is not affected.”
remove_channels_destroys_their_read_positions
L993 “destroys it when the Chat is destroyed” holds for a channel removed by Space/set removeChannels.
reply_counts_match_fixture
L638-642 (jmap-chat-spec 91672c9) against the fixture, counted by hand:
reply_create_lists_parent_updated
RFC 8620 §5.1: “If the data changes, this string MUST change.” Creating a reply to A raises A’s replyCount from 1 to 2 (L638-639), so Message/changes lists A as updated and the reply as created.
reply_destroy_lists_parent_updated
RFC 8620 §5.1: “If the data changes, this string MUST change.” Destroying B, the only reply to A, lowers A’s replyCount from 1 to 0, so Message/changes lists A as updated and B as destroyed.
run
Run test to completion on a fresh multi-thread tokio runtime with four workers, so the concurrency tests race on real threads.
sender_expires_at_hard_deletes_at_deadline
L747 (jmap-chat-spec 77c3474), §Message senderExpiresAt: “servers SHOULD permanently delete this message — removing the row entirely, not leaving a tombstone — at or before this time. A hard-deleted message appears in the destroyed list of subsequent Message/changes responses, not updated.”
space_destroy_destroys_channel_read_positions
Destroying a Space destroys its channel Chats (§Destroying a Space), so their ReadPositions go too (L993).
space_join_creates_read_positions_for_its_channels
L993: “For channel Chats, a ReadPosition is created when the owner joins the containing Space.” Only that Space’s channels get one.
space_query_filters_name_substring
L1389 (jmap-chat-spec 33702a5) §Space/query: “Filter properties: name (String, substring match), isPublic (Boolean).”
space_query_sort_ascending_orders_by_property
RFC 8620 §5.5 Comparator isAscending: “If true, sort in ascending order.” The Spaces are created out of name order so creation order cannot satisfy the assertion.
space_query_sort_descending_reverses_order
RFC 8620 §5.5 Comparator isAscending: “If false, reverse the comparator’s results to sort in descending order.”
state_advances_after_create
Oracle: state advances after a successful create_object call.
top_level_object_value_replaces_property
Oracle: RFC 8620 §5.3: “Anything else: The value to set for this property (this may be a replacement or addition to the object being patched).” A top-level deliveryReceipts value replaces the whole property; the existing u1 entry is not merged into it.
unread_count_in_full_get
aa01dd7 L635: unreadCount is computed for a full Chat/get (no ids) as well.
unread_reply_count_without_read_position
L641-642 (jmap-chat-spec 91672c9) with no lastReadMessageId: no reply has been read, so the unread count equals the reply count (ROOT: A and C -> 2).