> For the complete documentation index, see [llms.txt](https://docs.labrador-kennel.io/async-unit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labrador-kennel.io/async-unit/reference/events.md).

# Events

Information about the state of the framework while it is executing test suites can be retrieved by listening for semantic events emitted throughout the test running process. We utilize [Labrador AsyncEvent](https://github.com/labrador-kennel/async-event) for this which allows easily sharing a wealth of information with first-class awareness of Amp's Loop! In this section we list out what events are triggered by the framework and what information you can expect to have access to for each event.

{% hint style="info" %}
All of the classes below exist under the `Cspray\AsyncUnit` namespace. This portion of the namespace has been left out for brevity.
{% endhint %}

### Event Lifecycle

After we have finished parsing your tests and have started executing your test suites a series of events will be emitted. These events are intended to provide you information on what's happening within the framework to do anything that you might need to do; print result output, generate build artifacts, and otherwise decipher information about the results of your test suites. Each of the events listed below are emitted in order and, unless otherwise documented, can be emitted 1 or more times.

| Name                               | Event                               | Target                                 |
| ---------------------------------- | ----------------------------------- | -------------------------------------- |
| `Events::TEST_PROCESSING_STARTED`  | `Event\TestProcessingStartedEvent`  | `Statistics\AggregateSummary`          |
| `Events::TEST_SUITE_STARTED`       | `Event\TestSuiteStartedEvent`       | `Statistics\TestSuiteSummary`          |
| `Events::TEST_CASE_STARTED`        | `Event\TestCaseStartedEvent`        | `Statistics\TestCaseSummary`           |
| `Events::TEST_PROCESSED`           | `Event\TestProcessedEvent`          | `TestResult`                           |
| `Events::TEST_PASSED`              | `Event\TestPassedEvent`             | `TestResult`                           |
| `Events::TEST_FAILED`              | `Event\TestFailedEvent`             | `TestResult`                           |
| `Events::TEST_DISABLED`            | `Event\TestDisabledEvent`           | `TestResult`                           |
| `Events::TEST_CASE_FINISHED`       | `Event\TestCaseFinishedEvent`       | `Statistics\ProcessedTestCaseSummary`  |
| `Events::TEST_SUITE_FINISHED`      | `Event\TestSuiteFinishedEvent`      | `Statistics\ProcessedTestSuiteSummary` |
| `Events::TEST_PROCESSING_FINISHED` | `Event\TestProcessingFinishedEvent` | `Statistics\ProcessedAggregateSummary` |

### Event Details

#### Events::TEST\_PROCESSING\_STARTED

An event that is emitted exactly one time, after your test information has been parsed and immediately before tests start running. This event's target includes information about how many tests are going to be executed.

#### Events::TEST\_SUITE\_STARTED

An event that is emitted many times, once for each specified `TestSuite` before any `TestCase` associated have started processing. This event is guaranteed to be emitted at least once in case you're using the `ImplicitTestSuite`that gets utilized if you don't explicitly specify a `TestSuite`. This event will be emitted even if a `TestSuite` has been marked as disabled.

#### Events::TEST\_CASE\_STARTED

An event that is emitted many times, once for each specified `TestCase` before any tests associated are processed. This event will be emitted even if a `TestCase` has been marked as disabled.

#### Events::TEST\_PROCESSED

An event that is emitted many times, after *every* test has been processed. The test executed for this event may have passed, failed, or been marked disabled. Generally you should make use of the `TEST_PASSED`, `TEST_FAILED`, and `TEST_DISABLED` events instead. However, if you need access to everything this could be a good event to listen to. The `TestResult` will also provide access to information about the test that was run, including the `TestCase` instance used to run the test.

#### Events::TEST\_PASSED

An event that is emitted many times, after each test processing that was considered successful. Generally to be considered successful a test must have made at least 1 assertion that did not result in errors. However, based on the expectations in the test other conditions might have occurred, such as the throwing of an exception, that caused the test to be considered passed. The `TestResult` is the same instance passed to the `TEST_PROCESSED` event. This event will not be emitted if the test has failed or has been disabled.

#### Events::TEST\_FAILED

An event that is emitted many times, after each test processing that was considered a failure. Generally to be considered failing a test must have failed to make at least 1 assertion or some exception was thrown. However, based on the expectations in the test other conditions might have occurred, such as not throwing an expected exception, that caused the test to be considered passed. The `TestResult` is the same instance passed to the `TEST_PROCESSED` event. This event will not be emitted if the test has passed or has been disabled.

#### Events::TEST\_DISABLED

An events that is emitted many times, after each test processing that the test was marked as disabled. To be marked as disabled the test, `TestCase`, or `TestSuite` should be annotated with the `Disabled` Attribute. The `TestResult` is the same instance passed to the `TEST_PROCESSED` event. This event will not be emitted if the test has passed or failed.

#### Events::TEST\_CASE\_FINISHED

An event that is emitted many times, after all tests for the given `TestCase` have finished processing. This event will be emitted even if a `TestCase` has been marked as disabled.

#### Events::TEST\_SUITE\_FINISHED

An event that is emitted many times, once for each specified `TestSuite` after all `TestCase` associated have finished processing. This event is guaranteed to be emitted at least once in case you're using the `ImplicitTestSuite`that gets utilized if you don't explicitly specify a `TestSuite`. This event will be emitted even if a `TestSuite` has been marked as disabled.

#### Events::TEST\_PROCESSING\_FINISHED

An event that is emitted exactly one time, after *all* tests have finished processing and immediately before the application exits. This event's target includes information about the state of the tests that were executed.