NAME

TB2::EventHandler - A role which handles events and results

SYNOPSIS

  package My::EventHandler;

  use TB2::Mouse;
  with "TB2::EventHandler";

  # handle_result() handles result events
  sub handle_result {
      my $self = shift;
      my($result, $ec) = @_;

      ...
  }

  # handle_comment() handles comment events... and so on
  sub handle_comment {
      my $self = shift;
      my($comment, $ec) = @_;

      ...
  }


  # handle_event() handles anything not handled by some other method
  sub handle_event  {
      my $self = shift;
      my($event, $ec) = @_;

      ....
  }

  no TB2::Mouse;

DESCRIPTION

An EventHandler is made known to an EventCoordinator which gives it Events and Results to do whatever it wants with. EventHandlers can be used to record events for future use (such as TB2::History), to take an action like producing output (such as TB2::Formatter) or even modifying the event itself.

METHODS

accept_event

    $handler->accept_event($event, $event_coordinator);

Pass an $event and the $event_coordinator managing it to the $handler. The $handler will then pass them along to the appropriate handler method based on the $event->event_type. If the appropriate handler method does not exist, it will pass it to <handle_event>.

This is the main interface to pass events to an EventHandler. You should not pass events directly to handler methods as they may not exist.

subtest_handler

    my $subtest_handler = $handler->subtest_handler($subtest_start_event);

When a subtest starts, the TestState will call subtest_handler on each EventHandler to get a handler for the subtest. It will be passed in the $subtest_start_event (see TB2::Event::SubtestStart).

The provided method simply returns a new instance of the $handler's class which should be sufficient for most handlers.

You may override this to, for example, configure the new instance. Or to return the same instance if you want a single instance to handle all subtests.

Event handlers

EventHandlers process events via event handler methods. They are all of the form "handle_".$event->event_type. So a "comment" event is handled by handle_comment.

Event handlers are all called like this:

    $handler->handle_thing($event, $event_coordinator);

$event is the event being handled.

$event_coordinator is the coordinator which is managing the $event. This allows a handler to issue their own Events or access history via $ec->history.

A handler is allowed to alter the $event. Those changes will be visible to other EventHandlers down the line.

Event handler methods should not be called directly. Instead use accept_event.

handle_event

    $event_handler->handle_event($event, $event_coordinator);

This handles any event not handled by a more specific event handler (such as handle_result).

By default it does nothing.

EXAMPLE

Here is an example of an EventHandler which formats the results as a stream of pluses and minuses.

    package My::Formatter::PlusMinus;

    use TB2::Mouse;

    # This provides write(), otherwise it's a normal EventHandler
    extends 'TB2::Formatter';

    # Output a newline when we're done testing.
    sub handle_test_end {
        my $self  = shift;
        my $event = shift;

        $self->write(output => "\n");
        return;
    }

    # Print a plus for passes, minus for failures.
    sub handle_result {
        my $self   = shift;
        my $result = shift;

        my $out = $result->is_fail ? "-" : "+";
        $self->write(output => $out);

        return;
    }

    1;

cpanm Test::Simple

perl -MCPAN -e shell
install Test::Simple