From a6cde30ea5df30b8f1cafe4a7894588c6ba0499c Mon Sep 17 00:00:00 2001
From: Luca Tumedei <luca@theaveragedev.com>
Date: Tue, 18 Jun 2024 10:00:01 +0200
Subject: [PATCH] doc(extensions,dispatcher) add, rework

---
 docs/DispatcherAPI.md                      | 444 +++++++++++++++++++++
 docs/extensions.md                         |  10 -
 docs/extensions/BuiltInServerController.md |   6 +-
 docs/extensions/ChromeDriverController.md  |   8 +-
 docs/extensions/DockerComposeController.md |   6 +-
 docs/extensions/EventDispatcherBridge.md   | 151 +++++++
 docs/extensions/IsolationSupport.md        |   6 +-
 docs/extensions/Symlinker.md               |   2 -
 mkdocs.yml                                 |  10 +-
 9 files changed, 610 insertions(+), 33 deletions(-)
 create mode 100644 docs/DispatcherAPI.md
 delete mode 100644 docs/extensions.md
 create mode 100644 docs/extensions/EventDispatcherBridge.md

diff --git a/docs/DispatcherAPI.md b/docs/DispatcherAPI.md
new file mode 100644
index 000000000..3582b4554
--- /dev/null
+++ b/docs/DispatcherAPI.md
@@ -0,0 +1,444 @@
+An API to dispatch and subscribe to events fired during tests execution.
+
+### Events dispatched by Codeception
+
+You can subscribe to the following events dispatched by Codeception in either the global bootstrap file
+(usually `tests/_bootstrap.php`), or in a suite bootstrap file (usually `tests/<suite>/_bootstrap.php`) using the
+[Event Dispatcher Bridge extension][1]:
+
+* `Codeception\Events::SUITE_BEFORE`
+* `Codeception\Events::SUITE_AFTER`
+* `CodeceptionventsEvents::TEST_START`
+* `CodeceptionventsEvents::TEST_BEFORE`
+* `CodeceptionventsEvents::STEP_BEFORE`
+* `CodeceptionventsEvents::STEP_AFTER`
+* `CodeceptionventsEvents::TEST_FAIL`
+* `CodeceptionventsEvents::TEST_ERROR`
+* `CodeceptionventsEvents::TEST_PARSED`
+* `CodeceptionventsEvents::TEST_INCOMPLETE`
+* `CodeceptionventsEvents::TEST_SKIPPED`
+* `CodeceptionventsEvents::TEST_WARNING`
+* `CodeceptionventsEvents::TEST_USELESS`
+* `CodeceptionventsEvents::TEST_SUCCESS`
+* `CodeceptionventsEvents::TEST_AFTER`
+* `CodeceptionventsEvents::TEST_END`
+* `CodeceptionventsEvents::TEST_FAIL_PRINT`
+* `CodeceptionventsEvents::RESULT_PRINT_AFTER`
+
+In the global bootstrap file (usually `tests/_bootstrap.php`), or the suite bootstrap file (usually
+`tests/<suite>/_bootstrap.php`), subscribe to the Codeception events by providing a callback function that will accept
+different parameters depending on the event being dispatched:
+
+```php
+<?php
+
+use Codeception\Events;
+use Codeception\Event\SuiteEvent
+use Codeception\Event\TestEvent;
+use Codeception\Event\StepEvent;
+use Codeception\Event\PrintResultEvent;
+use lucatume\WPBrowser\Events\Dispatcher;
+
+Dispatcher::addListener(Events::SUITE_BEFORE, function (SuiteEvent $suiteEvent) {
+    codecept_debug('Running on SUITE BEFORE');
+});
+
+Dispatcher::addListener(Events::SUITE_AFTER, function (SuiteEvent $suiteEvent) {
+    codecept_debug('Running on SUITE AFTER');
+});
+
+Dispatcher::addListener(Events::TEST_START, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST START');
+});
+
+Dispatcher::addListener(Events::TEST_BEFORE, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST BEFORE');
+});
+
+Dispatcher::addListener(Events::STEP_BEFORE, function (StepEvent $stepEvent) {
+    codecept_debug('Running on STEP BEFORE');
+});
+
+Dispatcher::addListener(Events::STEP_AFTER, function (StepEvent $stepEvent) {
+    codecept_debug('Running on STEP AFTER');
+});
+
+Dispatcher::addListener(Events::TEST_FAIL, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST FAIL');
+});
+
+Dispatcher::addListener(Events::TEST_ERROR, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST ERROR');
+});
+
+Dispatcher::addListener(Events::TEST_PARSED, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST PARSED');
+});
+
+Dispatcher::addListener(Events::TEST_INCOMPLETE, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST INCOMPLETE');
+});
+
+Dispatcher::addListener(Events::TEST_SKIPPED, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST SKIPPED');
+});
+
+Dispatcher::addListener(Events::TEST_WARNING, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST WARNING');
+});
+
+Dispatcher::addListener(Events::TEST_USELESS, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST USELESS');
+});
+
+Dispatcher::addListener(Events::TEST_SUCCESS, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST SUCCESS');
+});
+
+Dispatcher::addListener(Events::TEST_AFTER, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST AFTER');
+});
+
+Dispatcher::addListener(Events::TEST_END, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST END');
+});
+
+Dispatcher::addListener(Events::TEST_FAIL_PRINT, function (PrintResultEvent $printResultEvent) {
+    codecept_debug('Running on TEST FAIL PRINT');
+});
+
+Dispatcher::addListener(Events::RESULT_PRINT_AFTER, function (PrintResultEvent $printResultEvent) {
+    codecept_debug('Running on RESULT PRINT AFTER');
+});
+```
+
+### Events dispatched by wp-browser
+
+The project dispatches its own events, allowing you to subscribe to them to control the test state and execution.  
+To subscribe to the events dispatched by wp-browser, you **do not need** to use the
+[Event Dispatcher Bridge extension][1].
+
+#### Events dispatched by the WPLoader module
+
+The [`WPLoader` module][2] will dispatch events during its initialization.  
+
+##### EVENT_BEFORE_LOADONLY
+
+This event fires before WordPress is loaded by the `WPLoader` module when `loadOnly` is set to `true`.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+WordPress is not loaded yet, so you cannot use functions or classes defined by WordPress, themes or plugins here.  
+You can interact with the WordPress installation and use the `lucatume\WPBrowser\WordPress\PreloadFilters` class to
+hook on actions and filters that will be fired by WordPress once loaded.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPLoader;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPLoader::EVENT_BEFORE_LOADONLY, function (Event $event) {
+    /** @var WPLoader $wpLoader */
+    $wpLoader = $event->getOrigin();
+    
+    codecept_debug('Running on EVENT_BEFORE_LOADONLY');
+   
+    // Interact with the WordPress installation, its filesystem and database.
+    $installation = $wpLoader->getInstallation();
+    $pluginsDir = $installation->getPluginsDir();
+    $db = $installation->getDb();
+    $db->import(codecept_data_dir('some-dump.sql'));
+    
+    // Use the PreloadFilters class to hook on WordPress actions and filters.
+    PreloadFilters::addFilter('init', fn() => update_option('some_option', 'some_value'));
+    PreloadFilters::addFilter('pre_option_some_option', fn() => 'some_value');
+});
+```
+
+##### EVENT_AFTER_LOADONLY
+
+This event fires after WordPress is loaded by the `WPLoader` module when `loadOnly` is set to `true`.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+At this point, WordPress has been loaded.
+You can interact with the WordPress installation using functions and classes defined by WordPress, themes or plugins.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPLoader;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPLoader::EVENT_AFTER_LOADONLY, function (Event $event) {
+    /** @var WPLoader $wpLoader */
+    $wpLoader = $event->getOrigin();
+    
+    codecept_debug('Running on EVENT_AFTER_LOADONLY');
+           
+    // Interact with the WordPress installation, its filesystem and database.    
+    $installation = $wpLoader->getInstallation();
+    $pluginsDir = $installation->getPluginsDir();
+    $db = $installation->getDb();
+    $db->import(codecept_data_dir('some-dump.sql'));
+    
+    // Use WordPress functions and classes.
+    update_option('some_option', 'some_value');
+});
+```
+
+##### EVENT_BEFORE_INSTALL
+
+This event fires before WordPress is installed by the `WPLoader` module when `loadOnly` is set to `false`.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+WordPress is not loaded yet, so you cannot use functions or classes defined by WordPress, themes or plugins here.  
+You can interact with the WordPress installation and use the `lucatume\WPBrowser\WordPress\PreloadFilters` class to
+hook on actions and filters that will be fired by WordPress once loaded.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPLoader;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPLoader::EVENT_BEFORE_INSTALL, function (Event $event) {
+    /** @var WPLoader $wpLoader */
+    $wpLoader = $event->getOrigin();
+    
+    codecept_debug('Running on EVENT_BEFORE_INSTALL');
+    
+    // Interact with the WordPress installation, its filesystem and database.
+    $installation = $wpLoader->getInstallation();
+    $pluginsDir = $installation->getPluginsDir();
+    $db = $installation->getDb();
+    $db->import(codecept_data_dir('some-dump.sql'));
+    
+    // Use the PreloadFilters class to hook on WordPress actions and filters.
+    PreloadFilters::addFilter('init', fn() => update_option('some_option', 'some_value'));
+    PreloadFilters::addFilter('pre_option_some_option', fn() => 'some_value');
+});
+```
+
+##### EVENT_AFTER_INSTALL
+
+This event fires after WordPress is installed by the `WPLoader` module when `loadOnly` is set to `false`.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+At this point, WordPress has been installed and loaded.
+You can interact with the WordPress installation using functions and classes defined by WordPress, themes or plugins.
+This event fires before dump files specified in the `dump` configuration parameter of the `WPLoader` module are
+imported.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPLoader;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPLoader::EVENT_AFTER_INSTALL, function (Event $event) {
+    /** @var WPLoader $wpLoader */
+    $wpLoader = $event->getOrigin();
+    
+    codecept_debug('Running on EVENT_AFTER_INSTALL');
+           
+    // Interact with the WordPress installation, its filesystem and database.    
+    $installation = $wpLoader->getInstallation();
+    $pluginsDir = $installation->getPluginsDir();
+    $db = $installation->getDb();
+    $db->import(codecept_data_dir('some-dump.sql'));
+    
+    // Use WordPress functions and classes.    
+    update_option('some_option', 'some_value');
+});
+```
+
+##### EVENT_AFTER_INSTALL
+
+This event fires after WordPress is installed by the `WPLoader` module when `loadOnly` is set to `false`. 
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+At this point, WordPress has been installed and loaded.
+You can interact with the WordPress installation using functions and classes defined by WordPress, themes or plugins.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPLoader;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPLoader::EVENT_AFTER_INSTALL, function (Event $event) {
+    /** @var WPLoader $wpLoader */
+    $wpLoader = $event->getOrigin();
+    
+    codecept_debug('Running on EVENT_AFTER_INSTALL');
+           
+    // Interact with the WordPress installation, its filesystem and database.    
+    $installation = $wpLoader->getInstallation();
+    $pluginsDir = $installation->getPluginsDir();
+    $db = $installation->getDb();
+    $db->import(codecept_data_dir('some-dump.sql'));
+    
+    // Use WordPress functions and classes.
+    update_option('some_option', 'some_value');
+});
+```
+
+##### EVENT_AFTER_BOOTSTRAP
+
+This event fires after the `WPLoader` module has finished bootstrapping the WordPress installation and dump files
+specified in the `dump` configuration parameter of the `WPLoader` module are imported.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+You can interact with the WordPress installation using functions and classes defined by WordPress, themes or plugins.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPLoader;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPLoader::EVENT_AFTER_BOOTSTRAP, function (Event $event) {
+    /** @var WPLoader $wpLoader */
+    $wpLoader = $event->getOrigin();
+    
+    codecept_debug('Running on EVENT_AFTER_BOOTSTRAP');
+    
+    // Interact with the WordPress installation, its filesystem and database.    
+    $installation = $wpLoader->getInstallation();
+    $pluginsDir = $installation->getPluginsDir();
+    $db = $installation->getDb();
+    $db->import(codecept_data_dir('some-dump.sql'));
+    
+    // Use WordPress functions and classes.
+    update_option('some_option', 'some_value');
+});
+```
+
+#### Events dispatched by the WPDb module
+
+##### EVENT_BEFORE_SUITE
+
+This event fires after the `WPDb` module has run its `_beforeSuite` method.  
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+At this point the module has connected to the database, cleaned up and populated the database with the dump files.
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPDb;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPDb::EVENT_BEFORE_SUITE, function (Event $event) {
+    /** @var WPDb $wpDb */
+    $wpDb = $event->getOrigin();    
+    
+    codecept_debug('Running on EVENT_BEFORE_SUIT
+    E');
+});
+```     
+
+##### EVENT_BEFORE_INITIALIZE
+
+This event fires before the `WPDb` module initializes.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Module\WPDb;
+use lucatume\WPBrowser\Events\Event;
+
+Dispatcher::addListener(WPDb::EVENT_BEFORE_INITIALIZE, function (Event $event) {
+    /** @var WPDb $wpDb */
+    $wpDb = $event->getOrigin();    
+    
+    codecept_debug('Running on EVENT_BEFORE_INITIALIZE');
+});
+``` 
+
+##### EVENT_AFTER_INITIALIZE
+
+This event fires after the `WPDb` module has initialized.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;  
+use lucatume\WPBrowser\Module\WPDb;  
+use lucatume\WPBrowser\Events\Event;  
+
+Dispatcher::addListener(WPDb::EVENT_AFTER_INITIALIZE, function (Event $event) {
+    /** @var WPDb $wpDb */
+    $wpDb = $event->getOrigin();    
+    
+    codecept_debug('Running on EVENT_AFTER_INITIALIZE');
+});
+```
+
+##### EVENT_AFTER_DB_PREPARE
+
+This event fires after the `WPDb` module has prepared the database setting up some default values for
+quality-of-life improvements.
+
+**Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).**
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;  
+use lucatume\WPBrowser\Module\WPDb;  
+use lucatume\WPBrowser\Events\Event;  
+
+Dispatcher::addListener(WPDb::EVENT_AFTER_DB_PREPARE, function (Event $event) {
+    /** @var WPDb $wpDb */
+    $wpDb = $event->getOrigin();    
+    
+    codecept_debug('Running on EVENT_AFTER_DB_PREPARE');
+});
+```     
+
+### Dispatching custom events
+
+You can use the `Dispatcher::dispatch` method to dispatch and subscribe to custom events:
+
+```php
+<?php
+
+use lucatume\WPBrowser\Events\Dispatcher;
+use lucatume\WPBrowser\Events\Event;  
+
+Dispatcher::dispatch('my-event', 'my-origin', ['foo' => 'bar']);
+
+// Some other code...
+Dispatcher::addListener('my-event', function (Event $event) {
+    $origin = $event->getOrigin();
+    $foo = $event->get('foo');
+    codecept_debug('Running on my custom event');
+});
+```
+
+[1]: extensions/EventDispatcherBridge.md
+
+[2]: modules/WPLoader.md
+
+[3]: modules/WPDb.md
+
diff --git a/docs/extensions.md b/docs/extensions.md
deleted file mode 100644
index 4fbffe864..000000000
--- a/docs/extensions.md
+++ /dev/null
@@ -1,10 +0,0 @@
-## Codeception Extensions provided by the library
-
-The library provides custom Codeception extensions that can be added to the project configuration
-file, `codeception.yml` or `codeception.dist.yml` by default, in the `extensions` section.
-
-* [BuiltInServerController](extensions/BuiltInServerController.md)
-* [ChromeDriverController](extensions/ChromeDriverController.md)
-* [DockerComposeController](extensions/DockerComposeController.md)
-* [IsolationSupport](extensions/IsolationSupport.md)
-* [Symlinker](extensions/Symlinker.md)
diff --git a/docs/extensions/BuiltInServerController.md b/docs/extensions/BuiltInServerController.md
index 89d97720b..ea5b68f51 100644
--- a/docs/extensions/BuiltInServerController.md
+++ b/docs/extensions/BuiltInServerController.md
@@ -1,5 +1,3 @@
-## Built-in Server Controller
-
 This extension will start and stop the PHP built-in web server before and after the tests run.
 
 ### Configuration
@@ -51,6 +49,6 @@ extensions:
 
 ### This is a service extension
 
-This is a service extension that will be started and stopped by [the `dev:start`](commands.md#devstart)
-and [`dev:stop`](commands.md#devstop) commands.
+This is a service extension that will be started and stopped by [the `dev:start`](../commands.md#devstart)
+and [`dev:stop`](../commands.md#devstop) commands.
 
diff --git a/docs/extensions/ChromeDriverController.md b/docs/extensions/ChromeDriverController.md
index ad2129c9d..e1bcb0510 100644
--- a/docs/extensions/ChromeDriverController.md
+++ b/docs/extensions/ChromeDriverController.md
@@ -1,5 +1,3 @@
-## ChromeDriver Controller Extension
-
 This extension will start and stop the ChromeDriver before and after the tests are run.
 
 ### Configuration
@@ -42,10 +40,10 @@ extensions:
       binary: '%CHROMEDRIVER_BINARY%'
 ```
 
-You can use [the `chromedriver:update` command](commands.md#chromedriverupdate) to download the latest version of
+You can use [the `chromedriver:update` command](../commands.md#chromedriverupdate) to download the latest version of
 ChromeDriver compatible with your Chrome browser version and place it in the Composer `bin` directory.
 
 ### This is a service extension
 
-This is a service extension that will be started and stopped by [the `dev:start`](commands.md#devstart)
-and [`dev:stop`](commands.md#devstop) commands.
+This is a service extension that will be started and stopped by [the `dev:start`](../commands.md#devstart)
+and [`dev:stop`](../commands.md#devstop) commands.
diff --git a/docs/extensions/DockerComposeController.md b/docs/extensions/DockerComposeController.md
index 11088b53f..d22596c8a 100644
--- a/docs/extensions/DockerComposeController.md
+++ b/docs/extensions/DockerComposeController.md
@@ -1,5 +1,3 @@
-## DockerCompose Controller Extension
-
 This extension will start and stop [a `docker compose` stack][1] before and after the tests are run.
 
 ### Configuration
@@ -40,7 +38,7 @@ extensions:
 
 ### This is a service extension
 
-This is a service extension that will be started and stopped by [the `dev:start`](commands.md#devstart)
-and [`wp:dev-stop`](commands.md#devstop) commands.
+This is a service extension that will be started and stopped by [the `dev:start`](../commands.md#devstart)
+and [`wp:dev-stop`](../commands.md#devstop) commands.
 
 [1]: https://docs.docker.com
diff --git a/docs/extensions/EventDispatcherBridge.md b/docs/extensions/EventDispatcherBridge.md
new file mode 100644
index 000000000..b7af05713
--- /dev/null
+++ b/docs/extensions/EventDispatcherBridge.md
@@ -0,0 +1,151 @@
+This extension connects the event dispatcher system provided by Codeception, and [normally available only through the
+use of custom extensions][1], to make it available through calls to the `lucatume\WPBrowser\Events\Dispatcher` class 
+API.
+
+If not using this extension, then the only way to subscribe to events dispatched by Codeception is to use [custom
+extensions][1].
+
+### Configuration
+
+The extension does not require configuration, it just needs to be enabled in the Codeception configuration file:
+
+```yaml
+extensions:
+  enabled:
+    - "lucatume\\WPBrowser\\Extension\\EventDispatcherBridge"
+```
+
+### Usage
+
+The extension will automatically hook into the event dispatcher system provided by Codeception, [normally available only
+through the use of custom extensions][1], and inject user-defined event listeners in it.
+
+Once the extension is enabled, you can use the `lucatume\WPBrowser\Events\Dispatcher` class to subscribe to Codeception 
+events.  
+This is typically be done in either the global bootstrap file, or in a suite bootstrap file.  
+
+You can subscribe to the following events dispatched by Codeception in either the global bootstrap file 
+(usually `tests/_bootstrap.php`), or in a suite bootstrap file (usually `tests/<suite>/_bootstrap.php`):
+
+* `Codeception\Events::SUITE_BEFORE`
+* `Codeception\Events::SUITE_AFTER`
+* `CodeceptionventsEvents::TEST_START`
+* `CodeceptionventsEvents::TEST_BEFORE`
+* `CodeceptionventsEvents::STEP_BEFORE`
+* `CodeceptionventsEvents::STEP_AFTER`
+* `CodeceptionventsEvents::TEST_FAIL`
+* `CodeceptionventsEvents::TEST_ERROR`
+* `CodeceptionventsEvents::TEST_PARSED`
+* `CodeceptionventsEvents::TEST_INCOMPLETE`
+* `CodeceptionventsEvents::TEST_SKIPPED`
+* `CodeceptionventsEvents::TEST_WARNING`
+* `CodeceptionventsEvents::TEST_USELESS`
+* `CodeceptionventsEvents::TEST_SUCCESS`
+* `CodeceptionventsEvents::TEST_AFTER`
+* `CodeceptionventsEvents::TEST_END`
+* `CodeceptionventsEvents::TEST_FAIL_PRINT`
+* `CodeceptionventsEvents::RESULT_PRINT_AFTER`
+
+Due to order-of-operations, the earliest Codeception dispatched Event you can subscribe to is the `SUITE_BEFORE` one.  
+To subscribe to the following earlier events, you must implement an extension following the [custom extension][1]
+approach:
+
+* `Codeception\Events::MODULE_INIT`
+* `Codeception\Events::SUITE_INIT`
+
+The [Dispatcher API][2] documentation provides more details about the events dispatched by Codeception and wp-browser
+and examples on how to subscribe to them.
+
+### Usage Examples
+
+In the global bootstrap file (usually `tests/_bootstrap.php`), or the suite bootstrap file (usually 
+`tests/<suite>/_bootstrap.php`), subscribe to the Codeception events by providing a callback function that will accept
+different parameters depending on the event being dispatched:
+
+```php
+<?php
+
+use Codeception\Events;
+use Codeception\Event\SuiteEvent
+use Codeception\Event\TestEvent;
+use Codeception\Event\StepEvent;
+use Codeception\Event\PrintResultEvent;
+use lucatume\WPBrowser\Events\Dispatcher;
+
+Dispatcher::addListener(Events::SUITE_BEFORE, function (SuiteEvent $suiteEvent) {
+    codecept_debug('Running on SUITE BEFORE');
+});
+
+Dispatcher::addListener(Events::SUITE_AFTER, function (SuiteEvent $suiteEvent) {
+    codecept_debug('Running on SUITE AFTER');
+});
+
+Dispatcher::addListener(Events::TEST_START, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST START');
+});
+
+Dispatcher::addListener(Events::TEST_BEFORE, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST BEFORE');
+});
+
+Dispatcher::addListener(Events::STEP_BEFORE, function (StepEvent $stepEvent) {
+    codecept_debug('Running on STEP BEFORE');
+});
+
+Dispatcher::addListener(Events::STEP_AFTER, function (StepEvent $stepEvent) {
+    codecept_debug('Running on STEP AFTER');
+});
+
+Dispatcher::addListener(Events::TEST_FAIL, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST FAIL');
+});
+
+Dispatcher::addListener(Events::TEST_ERROR, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST ERROR');
+});
+
+Dispatcher::addListener(Events::TEST_PARSED, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST PARSED');
+});
+
+Dispatcher::addListener(Events::TEST_INCOMPLETE, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST INCOMPLETE');
+});
+
+Dispatcher::addListener(Events::TEST_SKIPPED, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST SKIPPED');
+});
+
+Dispatcher::addListener(Events::TEST_WARNING, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST WARNING');
+});
+
+Dispatcher::addListener(Events::TEST_USELESS, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST USELESS');
+});
+
+Dispatcher::addListener(Events::TEST_SUCCESS, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST SUCCESS');
+});
+
+Dispatcher::addListener(Events::TEST_AFTER, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST AFTER');
+});
+
+Dispatcher::addListener(Events::TEST_END, function (TestEvent $testEvent) {
+    codecept_debug('Running on TEST END');
+});
+
+Dispatcher::addListener(Events::TEST_FAIL_PRINT, function (PrintResultEvent $printResultEvent) {
+    codecept_debug('Running on TEST FAIL PRINT');
+});
+
+Dispatcher::addListener(Events::RESULT_PRINT_AFTER, function (PrintResultEvent $printResultEvent) {
+    codecept_debug('Running on RESULT PRINT AFTER');
+});
+```
+
+[Read more about the Dispatcher API here][2].
+
+[1]: https://codeception.com/docs/Customization#Extension
+[2]: ../DispatcherAPI.md
diff --git a/docs/extensions/IsolationSupport.md b/docs/extensions/IsolationSupport.md
index e5e9675f8..8a1233b82 100644
--- a/docs/extensions/IsolationSupport.md
+++ b/docs/extensions/IsolationSupport.md
@@ -1,5 +1,3 @@
-## Isolation Support Extension
-
 This extension provides support for the PHPUnit annotations `@runInSeparateProcess` and `@runTestsInSeparateProcesses`,
 and the PHPUnit attributes (PHPUnit 10+) `#[RunInSeparateProcess]` and `#[RunTestsInSeparateProcesses]`.  
 You can read more about these annotations and attributes in the [PHPUnit documentation about test isolation][1].
@@ -69,5 +67,5 @@ and [`monkey:cache:path`][3] commands to manage the monkey-patching cache.
 
 
 [1]: https://docs.phpunit.de/en/10.5/attributes.html#test-isolation
-[2]: commands.md#monkeycacheclear
-[3]:commands.md#monkeycachepath
+[2]: ../commands.md#monkeycacheclear
+[3]: ../commands.md#monkeycachepath
diff --git a/docs/extensions/Symlinker.md b/docs/extensions/Symlinker.md
index 8c8cf36d1..521f3ced9 100644
--- a/docs/extensions/Symlinker.md
+++ b/docs/extensions/Symlinker.md
@@ -1,5 +1,3 @@
-## Symlinker Extension
-
 This extension will symlink the plugins and themes specified in the `plugins` and `themes` configuration parameters to
 the WordPress installation plugins and themes directories, respectively.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index d2131dc15..adba2caf0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -24,10 +24,11 @@ nav:
       - WPWebDriver: 'modules/WPWebDriver.md'
       - Airplane Mode: 'modules/AirplaneMode.md'
   - Extensions:
-      - PHP Built-in Server Controller: 'extensions#builtinservercontroller'
-      - ChromeDriver Controller: 'extensions#chromedrivercontroller'
-      - Docker Compose Controller: 'extensions#dockercomposecontroller'
-      - Isolation Support: 'extensions#isolationsupport'
+      - PHP Built-in Server Controller: 'extensions/BuiltInServerController.md'
+      - ChromeDriver Controller: 'extensions/ChromeDriverController.md'
+      - Docker Compose Controller: 'extensions/DockerComposeController.md'
+      - Isolation Support: 'extensions/IsolationSupport.md'
+      - Event Dispatcher Bridge: 'extensions/EventDispatcherBridge.md'
   - Commands:
       - run and codeception:run: 'commands#run-and-codeceptionrun'
       - dev:start: 'commands#devstart'
@@ -48,6 +49,7 @@ nav:
       - monkey:cache:clear: 'commands#monkeycacheclear'
   - Helpers:
       - UopzFunctions trait: 'traits/UopzFunctions.md'
+      - Dispatcher API: 'DispatcherAPI.md'
   - Troubleshooting: 'troubleshooting.md'
   - Changelog: 'https://github.com/lucatume/wp-browser/blob/master/CHANGELOG.md'
   - v3: