Macro assert_event_sequence 

macro_rules! assert_event_sequence {
    ($stream: expr, [$($event:expr),+ $(,)?]) => { ... };
    ($stream: expr, [$($event:expr),+ $(,)?], timeout = $secs: expr) => { ... };
    ($stream: expr, &[$($event:expr),+ $(,)?]) => { ... };
    ($stream: expr, &[$($event:expr),+ $(,)?], timeout = $secs: expr) => { ... };
    ($stream: expr, $events: expr) => { ... };
    ($stream: expr, $events: expr, timeout = $secs: expr) => { ... };
}

Asserts that a stream emits a specific sequence of events in order.

This macro consumes messages from a stream and verifies that the provided events are emitted in the exact order specified, regardless of how they are batched. The stream may emit events across multiple batches or all at once—the macro handles both cases. It ensures no unexpected events appear between the expected ones and that the sequence completes exactly as specified.

The macro accepts events of any type implementing SolEvent. Events are compared by their encoded log data, allowing flexible matching across different batch configurations while maintaining strict ordering requirements.

Examples

sol! {
    event CountIncreased(uint256 newCount);
}

#[tokio::test]
async fn test_event_order() {
    // scanner setup...

    let subscription = scanner.subscribe(EventFilter::new().contract_address(contract_address));
    let handle = scanner.start().await.unwrap();
    let mut stream = subscription.stream(&handle);

    // Assert these two events are emitted in order
    assert_event_sequence!(
        stream,
        &[
            CountIncreased { newCount: U256::from(1) },
            CountIncreased { newCount: U256::from(2) },
        ]
    );
}

The assertion passes whether events arrive in separate batches or together:

• Separate batches: [Event1], then [Event2]
• Single batch: [Event1, Event2]

Panics

• Timeout: The stream doesn’t produce the next expected event within the timeout period (default 5 seconds, configurable via timeout = N parameter).
• Wrong event: The stream emits a different event than the next expected one in the sequence.
• Extra events: The stream emits more events than expected after the sequence completes.
• Stream closed early: The stream ends before all expected events are emitted.
• Wrong message type: The stream yields a non-Data message (e.g., Error or Status) when an event is expected.
• Empty sequence: The macro is called with an empty event collection (use assert_empty! instead).

On panic, the error message includes the remaining expected events for debugging.