# NAME

`Test::Async::Event` – collection of standard events

# SYNOPSIS

    use Test::Async::Event;

    test-bundle MyBundle {
        method foo(Str:D $message) is test-tool {
            self.send-test: Event::Ok, :$message
        }
    }

# DESCRIPTION

General information about `Test::Async` event management can be found in `Test::Async::Manual`.

Events are objects of classes derived from `Event` class. This module defines events used by the core. In general, all event classes can be conventionally split into the following groups:

- informative – events signalling about some state changes. Like, for example, suite termination.

- reporting - events bearing a message to be reported to user.

- commands – those which tell the core to perform an action.

- tests – outcomes of individual test tools.

# EXPORTED CLASSES

## Class `Event`

The base event class.

### Attributes

- `$.origin` – event originating object. Defaults to the current test suite object.

- `Int:D $.id` – event id, a sequential number.

- `Instant:D $.time` – the moment when event object was created.

### Methods

- `Profile` – returns a `Map` suitable for passing to an event constructor. The method collects all changed public attributes of an object.

- `gist`, `Str` – stringify event object for reporting.

## Class `Event::Report`

Is `Event`.

Base class for events carrying a text message of any kind.

### Attributes

- `Str:D $.message` – the event message

## Class `Event::Command`

Is `Event`.

Base class of commanding events. `Test::Async::Hub` handles them specially.

### Attributes

- `Capture:D $.args` – command arguments

## Class `Event::Test`

Is `Event::Report`

Base class for events reporting test outcomes.

### Attributes

- `Int:D $.test-id`, required – test number

- `Str $.todo` – message to use if test is marked as TODO.

- `Str $.flunks` – message to use if test is marked as anticipated failure (see `test-flunks` in `Test::Async::Base`.

- `CallFrame:D $.caller`, required – position in user code where the test was called.

- `@.child-messages` – messages from child suites. Each entry should be a single line ending with newline.

- `@.comments` – comments for the test. Normally expected to be reported with `diag`. Not special formatting requirements except for a recommendation for the last line not to end with a newline.

## Class `Event::Terminate`

Is `Event`.

This is the only kind of event which `Term::Async::Aggregator` role cares about. It tells the event loop to pull any remaining events from the queue and dispatch them immediately. Then it fulfills event's promise.

### Attributes

- `Promise::Vow $.completed`, required – a promise vow to be kept when event loop finishes processing all remaining events.

## Class `Event::Telemetry`

Is `Event`

Under development yet.

## Class `Event::Plan`

Is `Event::Report`

Plan reporting event. Emitted when a suite gets to know the number of tests to be done.

### Attributes

- `Bool $.skip` – suite is planned for skiping.

- `UInt:D $.planned`, required - number of tests planned.

## Class `Event::Diag`

Is `Event::Report`.

Carries a diagnostics message. See `diag` in `Test::Async::Base`.

## Class `Event::Ok`

Is `Event::Test`.

Test passed.

## Class `Event::NotOk`

Is `Event::Test`.

Test flunked.

## Class `Event::Skip`

Is `Event::Test`.

Test skipped.

## Class `Event::DoneTesting`

Is `Event::Report`.

Emitted when testing is completely done.

## Class `Event::BailOut`

Is `Event::Report`

Emitted when test suite is about to bail out.

## Command event classes `Event::Cmd::*`

A bundle of events used internally for commands. See `Test::Async::Hub` and possibly other modules. The set of command events is not standartized and subject for changes.

# SEE ALSO

`Test::Async::Manual`, `Test::Async::Aggregator`, `Test::Async::Hub`

# AUTHOR

Vadim Belman <vrurg@cpan.org>