Test2::Manual::Anatomy::Hubs - Internals documentation for the hub stack, and
hubs.
This document describes the hub stack, and the hubs it contains. It explains
why we have a stack, and when to add/remove hubs from it.
Test2 is an event system, tools generate events, those events are then
processed to modify the testing state (number of tests, number of failures,
etc). The hub is responsible for receiving and processing events to record the
change in state. All events should eventually reach a destination hub.
The base hub is the Test2::Hub manpage. All hub classes should inherit from the base hub
class. The base hub class provides several hooks that allow you to monitor or
modify events. Hubs are also responsible for forwarding events to the output
formatter.
There are cases where it makes sense to have more than one hub:
- subtests
-
In Test2 subtests are implemented using the hub stack. When you start a subtest
a new the Test2::Hub::Subtest manpage instance is created and pushed to the stack. Once
this is done all calls to
Test2::API::context will find the new hub and send
all events to it. When the subtest tool is complete it will remove the new hub,
and send a final subtest event to the parent hub.
- testing your test tools
-
Test2::API::intercept() is implemented using the hub stack. The
Test2::API::intercept() function will add an the Test2::Hub::Interceptor manpage
instance to the stack, any calls to the Test2::API::context() manpage will find the new
hub, and send it all events. The intercept hub is special in that is has no
connection to the parent hub, and usually does not have a formatter.
Any time you want to intercept or block events from effecting the test state.
Adding a new hub is essentially a way to create a sandbox where you have
absolute control over what events do. Adding a new hub insures that the main
test state will not be effected.
The stack is an instance of the Test2::API::Stack manpage. You can access the global hub
stack using Test2::API::test2_stack.
The root hub is created automatically as needed. A call to
Test2::API::test2_stack->top() will create the root hub if it does not
already exist.
If the IPC system (the Test2::IPC manpage) was not loaded, then IPC is not handled at
all. Forking or creating new threads without the IPC system can cause
unexpected problems.
All hubs track the PID and Thread ID that was current when they were created.
If an event is sent to a hub in a new process/thread the hub will detect this
and try to forward the event along to the correct process/thread. This is
accomplished using the IPC system.
the Test2::Manual manpage - Primary index of the manual.
The source code repository for Test2-Manual can be found at
https://github.com/Test-More/Test2-Suite/.
- Chad Granum
-
- Chad Granum <exodist@cpan.org>Chad Granum
-
Copyright 2018 Chad Granum <exodist@cpan.org>.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
See http://dev.perl.org/licenses/
|