'Context manager that captures all events emitted while executing a particular block.
All captured events are stored in the list referenced by `captured_events`. Note that this list is appended to
*in place*. The events will be appended to the list in the order they are emitted.
The `event_filter` is expected to be a callable that allows you to filter the event stream and select particular
events of interest. A dictionary `event_filter` is also supported, which simply indicates that the event should
match that provided expectation.
`number_of_matches` tells this context manager when enough events have been found and it can move on. The
context manager will not exit until this many events have passed the filter. If not enough events are found
before a timeout expires, then this will raise a `BrokenPromise` error. Note that this simply states that
*at least* this many events have been emitted, so `number_of_matches` is simply a lower bound for the size of
`captured_events`.'

@contextmanager
def capture_events(self, event_filter=None, number_of_matches=1, captured_events=None):

    start_time = datetime.utcnow()
    (yield)
    events = self.wait_for_events(start_time=start_time, event_filter=event_filter, number_of_matches=number_of_matches)
    if ((captured_events is not None) and hasattr(captured_events, 'append') and callable(captured_events.append)):
        for event in events:
            captured_events.append(event)
