NAME

       Test2::Manual::Anatomy::Context - Internals documentation for the Context objects.

DESCRIPTION

       This document explains how the Test2::API::Context object works.

WHAT IS THE CONTEXT OBJECT?

       The context object is one of the key components of Test2, and makes many features possible
       that would otherwise be impossible. Every test tool starts by getting a context, and ends
       by releasing the context. A test tool does all its work between getting and releasing the
       context. The context instance is the primary interface for sending events to the Test2
       stack. Finally the context system is responsible for tracking what file and line number a
       tool operates on, which is critical for debugging.

   PRIMARY INTERFACE FOR TEST TOOLS
       Nearly every Test2 based tool should start by calling "$ctx = Test2::API::context()" in
       order to get a context object, and should end by calling "$ctx->release()". Once a tool
       has its context object it can call methods on the object to send events or have other
       effects. Nearly everything a test tool needs to do should be done through the context
       object.

   TRACK FILE AND LINE NUMBERS FOR ERROR REPORTING
       When you call "Test2::API::Context" a new context object will be returned. If there is
       already a context object in effect (from a different point in the stack) you will get a
       clone of the existing one. If there is not already a current context then a completely new
       one will be generated. When a new context is generated Test2 will determine the file name
       and line number for your test code, these will be used when reporting any failures.

       Typically the file and line number will be determined using "caller()" to look at your
       tools caller. The $Test::Builder::Level will be respected if detected, but is discouraged
       in favor of just using context objects at every level.

       When calling "Test2::API::Context()" you can specify the "level => $count" arguments if
       you need to look at a deeper caller.

   PRESERVE $?, $!, $^E AND $@
       When you call "Test2::API::context()" the current values of $?, $!, $^E, and $@ are stored
       in the context object itself. Whenever the context is released the original values of
       these variables will be restored. This protects the variables from any side effects caused
       by testing tools.

   FINALIZE THE API STATE
       Test2::API works via a hidden singleton instance of Test2::API::Instance.  The singleton
       has some state that is not set in stone until the last possible minute. The last possible
       minute happens to be the first time a context is acquired. State includes IPC instance,
       Formatter class, Root PID, etc.

   FIND/CREATE THE CURRENT/ROOT HUB
       Test2 has a stack of hubs, the stack can be accessed via Test2::API::test2_stack. When you
       get a context it will find the current hub, if there is no current hub then the root one
       will be initialized.

   PROVIDE HOOKS
       There are hooks that run when contexts are created, found, and released. See Test2::API
       for details on these hooks and how to use them.

SEE ALSO

       Test2::Manual - Primary index of the manual.

SOURCE

       The source code repository for Test2-Manual can be found at
       https://github.com/Test-More/Test2-Suite/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       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/