feat: assert emitted events

[qalisander]

Resolves #9

PR Checklist

• Tests
• Documentation
• Changelog

[qalisander]

Should be reviewed after this pr #31

[qalisander]

That is the new syntax for events.
Although it is not possible print events, during failure with this approach. Since we just return boolean value.
But we can add this feature later.
@0xNeshi , @bidzyyys wdt?

[0xNeshi]

Although it is not possible print events, during failure with this approach.

I think something like:

        _ = ping
            .sender(alice)
            .ping(pong.address(), TEN)
            .expect("should ping successfully");

        // Assert emitted events.
        ping.assert_emitted(Pinged { from: alice.address(), value: TEN });

would allow for printing events, and is also far more in line with motsu's current approach.

---

Alternatives

• a new macro like assert_emitted! that would be able to print events.
• trait extension without macros:

Pinged { from: alice.address(), value: TEN }.assert_emitted();

I'd prefer the original proposal (contract.assert_emitted) as it would allow focusing the assertion on specific contracts. EDIT: I'd be ok with the macro as well, see explanation below.

[qalisander]

I planned to just have assert_emitted! macro for event's printing, but it would print all events from any contract in unit test. Assertion for events produced by specific contract ping.assert_emitted(Pinged { from: alice.address(), value: TEN }); can be quite convenient, I agree!

[0xNeshi]

I planned to just have assert_emitted! macro for event's printing, but it would print all events from any contract in unit test.

The macro could accept the contract parameter as well, thus focusing the check:

assert_emitted!(ping, Pinged { from: alice.address(), value: TEN });

I'm fine with both contract.assert_emitted and macro approach, as both seem idiomatic to Rust and convenient for motsu.

We could even provide both and let devs choose? 🤔

---

A nice(-to-have) feature would be to support specifying the number of times an event was emitted?

To give a dumb, and yet possible example where this would be useful would be a Vault that can execute multiple pending withdrawal requests in one transaction, collecting fees for the Vault owner and emitting something like FeeCollected for each withdrawal.

#[test]
fn multiple_withdrawals_work(
    owner: Account,
    alice: Account,
    bob: Account
) {
    let vault = Contract::<Vault>::new();

    // set up the vault

    // alice and bob invest in the vault
    
    // alice and bob initiate withdrawal requests
    
    vault.withdraw_pending().expect("ok");
    
    // Assert emitted exactly twice with macro
    assert_emitted!(vault, FeeCollected { }, 2);
    // or as a contract extension
    vault.assert_emitted(FeeCollected { }).times(2);
}