Introducing limit of times a mock is available

[ferranjr]

As proposed in #32 this introduces a little matcher helper to limit the amount of times a matcher successfully matches.

This enables testing of retries mechanisms on a client and hopefully help other cases too.

let mock = Mock::new(|when, then| {
    when.times(3, any());
    then.ok();
})

[declark1]

Thanks for the contribution @ferranjr. I see the new tonic release has some breaking changes causing this build to fail (I have the version loosely set to "0", not ideal for this reason). I'll fix that on main first.

[ferranjr]

@declark1 PR is now rebased with your changes

[declark1]

I was thinking about this further and I realized that it would probably be better to implement this specific feature at the mock-level (as an option, similar to priority), rather than at the matcher-level, so that the mock has a limit rather than one of it's specific matchers.

This wasn't initially possible as we didn't have a counter implemented yet to track the number of matches. I'm merging a batch of changes now, including adding match_count to Mock.

For this, I was thinking we can:

• Add limit: Option<usize> to Mock
  • Add with_limit() and limit() methods
• Add limit parameter to MockSet::mock_with_options() and MockServer::mock_with_options() methods
  • Previously named mock_with_priority, but I renamed it to be more flexible if we add additional options such as this
• Update Mock::matches() to add logic to return false if there is a limit and match_count exceeds it

The usage would then look like this:

// With Mock::new()
let mock = Mock::new(|when, then| {
    when.post().path(..).json(..);
    then.json(..);
})
.with_limit(2);

// With shorthand MockSet::mock_with_options()
let mut mocks = MockSet::new();
mocks.mock_with_options(priority, limit, |when, then|) {
    when.post().path(..).json(..);
    then.json(..);
    limit = Some(2);
}

What are your thoughts on this?

[ferranjr]

Yes, makes sense to move it to mock level... I noticed the changes on your other PR, and already was thinking how this could be change.

Definitely like the approach:

// With Mock::new()
let mock = Mock::new(|when, then| {
    when.post().path(..).json(..);
    then.json(..);
})
.with_limit(2);

Although, probably from working using other mocking libraries before, I am kind of bias towards times

// With Mock::new()
let mock = Mock::new(|when, then| {
    when.post().path(..).json(..);
    then.json(..);
}).times(2);

Maybe limit gives me an idea of no more calls are allowed... where times, if follow by another mock, gives an idea of the amount of times it behaves that way?

In any case, move it Mock level makes more sense, and we can implement it with the counter you have in that PR

[ferranjr]

BTW, happy to work on it later, I see you merged the changes already

[declark1]

Thanks @ferranjr, sure it would be great if you can add this. Apologies for the re-work. I suppose times works too, I don't really have a strong opinion on it.

[ferranjr]

@declark1 done the rework, and while doing it the with_limit made more sense, it makes it clear you are setting the value.

[declark1]

A couple nits to update names to limit, otherwise looks good, thanks!

[declark1]

nit: can you update times -> limit here and below in matches()

[declark1]

nit: rename to test_limit()

[declark1]

nit: reword docstring consistent with above:
/// Limit on how many times this mock can be matched.

[ferranjr]

sorted, clearly I was debating times vs limit till last second :)

[declark1]

Looks good, thanks!