1Test2::Manual::Anatomy:U:sCeorntCeoxntt(r3i)buted Perl DToecsutm2e:n:tMaatniuoanl::Anatomy::Context(3)
2
3
4

NAME

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

DESCRIPTION

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

WHAT IS THE CONTEXT OBJECT?

13       The context object is one of the key components of Test2, and makes
14       many features possible that would otherwise be impossible. Every test
15       tool starts by getting a context, and ends by releasing the context. A
16       test tool does all its work between getting and releasing the context.
17       The context instance is the primary interface for sending events to the
18       Test2 stack. Finally the context system is responsible for tracking
19       what file and line number a tool operates on, which is critical for
20       debugging.
21
22   PRIMARY INTERFACE FOR TEST TOOLS
23       Nearly every Test2 based tool should start by calling "$ctx =
24       Test2::API::context()" in order to get a context object, and should end
25       by calling "$ctx->release()". Once a tool has its context object it can
26       call methods on the object to send events or have other effects. Nearly
27       everything a test tool needs to do should be done through the context
28       object.
29
30   TRACK FILE AND LINE NUMBERS FOR ERROR REPORTING
31       When you call "Test2::API::Context" a new context object will be
32       returned. If there is already a context object in effect (from a
33       different point in the stack) you will get a clone of the existing one.
34       If there is not already a current context then a completely new one
35       will be generated. When a new context is generated Test2 will determine
36       the file name and line number for your test code, these will be used
37       when reporting any failures.
38
39       Typically the file and line number will be determined using "caller()"
40       to look at your tools caller. The $Test::Builder::Level will be
41       respected if detected, but is discouraged in favor of just using
42       context objects at every level.
43
44       When calling "Test2::API::Context()" you can specify the "level =>
45       $count" arguments if you need to look at a deeper caller.
46
47   PRESERVE $?, $!, $^E AND $@
48       When you call "Test2::API::context()" the current values of $?, $!,
49       $^E, and $@ are stored in the context object itself. Whenever the
50       context is released the original values of these variables will be
51       restored. This protects the variables from any side effects caused by
52       testing tools.
53
54   FINALIZE THE API STATE
55       Test2::API works via a hidden singleton instance of
56       Test2::API::Instance.  The singleton has some state that is not set in
57       stone until the last possible minute. The last possible minute happens
58       to be the first time a context is acquired. State includes IPC
59       instance, Formatter class, Root PID, etc.
60
61   FIND/CREATE THE CURRENT/ROOT HUB
62       Test2 has a stack of hubs, the stack can be accessed via
63       Test2::API::test2_stack. When you get a context it will find the
64       current hub, if there is no current hub then the root one will be
65       initialized.
66
67   PROVIDE HOOKS
68       There are hooks that run when contexts are created, found, and
69       released. See Test2::API for details on these hooks and how to use
70       them.
71

SEE ALSO

73       Test2::Manual - Primary index of the manual.
74

SOURCE

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

MAINTAINERS

80       Chad Granum <exodist@cpan.org>
81

AUTHORS

83       Chad Granum <exodist@cpan.org>
84
86       Copyright 2018 Chad Granum <exodist@cpan.org>.
87
88       This program is free software; you can redistribute it and/or modify it
89       under the same terms as Perl itself.
90
91       See http://dev.perl.org/licenses/
92
93
94
95perl v5.36.0                      2022-07-22Test2::Manual::Anatomy::Context(3)
Impressum