Debian Codegraph @

upstream/debian-unstable/man3/Test2::Manual::Anatomy::Context.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test2::Manual::Anatomy::Context 3perl"
58 .TH Test2::Manual::Anatomy::Context 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::Manual::Anatomy::Context \- Internals documentation for the Context
65 objects.
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 This document explains how the Test2::API::Context object works.
69 .SH "WHAT IS THE CONTEXT OBJECT?"
70 .IX Header "WHAT IS THE CONTEXT OBJECT?"
71 The context object is one of the key components of Test2, and makes many
72 features possible that would otherwise be impossible. Every test tool starts by
73 getting a context, and ends by releasing the context. A test tool does all its
74 work between getting and releasing the context. The context instance is the
75 primary interface for sending events to the Test2 stack. Finally the context
76 system is responsible for tracking what file and line number a tool operates
77 on, which is critical for debugging.
78 .SS "PRIMARY INTERFACE FOR TEST TOOLS"
79 .IX Subsection "PRIMARY INTERFACE FOR TEST TOOLS"
80 Nearly every Test2 based tool should start by calling \f(CW$ctx =
81 Test2::API::context()\fR in order to get a context object, and should end by
82 calling \f(CW\*(C`$ctx\->release()\*(C'\fR. Once a tool has its context object it can call
83 methods on the object to send events or have other effects. Nearly everything a
84 test tool needs to do should be done through the context object.
85 .SS "TRACK FILE AND LINE NUMBERS FOR ERROR REPORTING"
86 .IX Subsection "TRACK FILE AND LINE NUMBERS FOR ERROR REPORTING"
87 When you call \f(CW\*(C`Test2::API::Context\*(C'\fR a new context object will be returned. If
88 there is already a context object in effect (from a different point in the
89 stack) you will get a clone of the existing one. If there is not already a
90 current context then a completely new one will be generated. When a new context
91 is generated Test2 will determine the file name and line number for your test
92 code, these will be used when reporting any failures.
93 .PP
94 Typically the file and line number will be determined using \f(CWcaller()\fR to look
95 at your tools caller. The \f(CW$Test::Builder::Level\fR will be respected if
96 detected, but is discouraged in favor of just using context objects at every
97 level.
98 .PP
99 When calling \f(CWTest2::API::Context()\fR you can specify the
100 \&\f(CW\*(C`level => $count\*(C'\fR arguments if you need to look at a deeper caller.
101 .SS "PRESERVE $?, $!, $^E AND $@"
102 .IX Subsection "PRESERVE $?, $!, $^E AND $@"
103 When you call \f(CWTest2::API::context()\fR the current values of \f(CW$?\fR, \f(CW$!\fR,
104 \&\f(CW$^E\fR, and \f(CW$@\fR are stored in the context object itself. Whenever the context
105 is released the original values of these variables will be restored. This
106 protects the variables from any side effects caused by testing tools.
107 .SS "FINALIZE THE API STATE"
108 .IX Subsection "FINALIZE THE API STATE"
109 Test2::API works via a hidden singleton instance of Test2::API::Instance.
110 The singleton has some state that is not set in stone until the last possible
111 minute. The last possible minute happens to be the first time a context is
112 acquired. State includes IPC instance, Formatter class, Root PID, etc.
113 .SS "FIND/CREATE THE CURRENT/ROOT HUB"
114 .IX Subsection "FIND/CREATE THE CURRENT/ROOT HUB"
115 Test2 has a stack of hubs, the stack can be accessed via
116 Test2::API::test2_stack. When you get a context it will find the current
117 hub, if there is no current hub then the root one will be initialized.
118 .SS "PROVIDE HOOKS"
119 .IX Subsection "PROVIDE HOOKS"
120 There are hooks that run when contexts are created, found, and released. See
121 Test2::API for details on these hooks and how to use them.
122 .SH "SEE ALSO"
123 .IX Header "SEE ALSO"
124 Test2::Manual \- Primary index of the manual.
125 .SH SOURCE
126 .IX Header "SOURCE"
127 The source code repository for Test2\-Manual can be found at
128 \&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
129 .SH MAINTAINERS
130 .IX Header "MAINTAINERS"
131 .IP "Chad Granum <[email protected]>" 4
132 .IX Item "Chad Granum <[email protected]>"
133 .SH AUTHORS
134 .IX Header "AUTHORS"
135 .PD 0
136 .IP "Chad Granum <[email protected]>" 4
137 .IX Item "Chad Granum <[email protected]>"
138 .PD
139 .SH COPYRIGHT
140 .IX Header "COPYRIGHT"
141 Copyright 2018 Chad Granum <[email protected]>.
142 .PP
143 This program is free software; you can redistribute it and/or
144 modify it under the same terms as Perl itself.
145 .PP
146 See \fIhttp://dev.perl.org/licenses/\fR