1Test2::Harness::Log(3)User Contributed Perl DocumentationTest2::Harness::Log(3)
2
3
4

NAME

6       Test2::Harness::Log - Documentation about the Test2::Harness log file.
7

DESCRIPTION

9       Test2::Harness aka App::Yath produces a rich/complete log when asked to
10       do so. This module documents the log format.
11

COMPRESSION

13       Test2::Harness can output log files uncompressed, compressed in gzip,
14       or compressed in bzip2.
15

FORMAT

17       The log file is in jsonl format. Each line of the log can be
18       indepentantly parsed as json. Each line represents a single event
19       Test2::Harness processed during a run. These events will be in the
20       original order Test2::Harness processed them in (may not be
21       chronological to when they were generated as generation, collection,
22       processing, and rendering are handled in different processes. A
23       complete log will be terminated by the string "null", which is also
24       valid json. If a log is missing this terminator it is considered an
25       incomplete log.
26
27   EVENTS
28       Please note: Older versions of Test2::Harness produced less complete
29       events, this covers all current fields, if you are attempting to handle
30       very old logs some of these fields may be missing.
31
32       Each event will have the following fields:
33
34           {
35              "event_id" : "CD01CD30-D535-11EA-9B6A-D90F9664FE12",
36              "job_id"   : 0,
37              "job_try"  : null,
38              "run_id"   : "CCF98E54-D535-11EA-915A-D70F9664FE12",
39              "stamp"    : 1596423763.76517,
40
41              "facet_data" : {
42                 "harness" : {
43                    "event_id" : "CD01CD30-D535-11EA-9B6A-D90F9664FE12",
44                    "job_id" : 0,
45                    "job_try" : null,
46                    "run_id" : "CCF98E54-D535-11EA-915A-D70F9664FE12"
47                 },
48
49                 ...
50              }
51           }
52
53       event_id : "UUID_OR_STRING"
54           Typically this will be a UUID, but when UUIDs cannot be generated
55           it may have a different unique identifier. This will always be a
56           string. This may never be NULL, if it is NULL then that is a bug
57           and should be reported.
58
59       job_id : "0_OR_UUID_OR_STRING"
60           ID 0 is special in that it represents the test harness itself, and
61           not an actual test being run. Normally the job_id will be a UUID,
62           but may be another unique string if UUID generation is disabled or
63           not available.
64
65       job_try : INTEGER_OR_NULL
66           For "job_id => 0" this will be "NULL" for any other job this will
67           be an intgeger of 0 or greater. This is 0 for the first time a test
68           job is run, if a job is re-run due to failure (or any other reason)
69           this will be incremented to tell you what run it is. When a job is
70           re-run it keeps the same job ID, you can use this to distinguish
71           events from each run of the job.
72
73       run_id : "UUID_OR_STRING"
74           This is the run_id of the entire yath test run. This should be the
75           same for every event in any given log.
76
77       stamp : UNIX_TIME_STAMP
78           Timestamp of the event. This is NORMALLY set when an event is
79           generated, however if an event does not have its own time stamp
80           yath will give it a timestamp upon collection. Events without
81           timestamps happen if the test outputs TAP instead of Test2::Event
82           objects, or if a tool misbehaves in some way.
83
84       facet_data : HASH
85           This contains all the the data of the event, such as if an
86           assertion was made, what file name and line number generated it,
87           etc.
88
89           In addition to the original facets of the event, Test2::Harness may
90           inject the following facets (or generate completely new events to
91           convey these facets).
92
93           harness_final
94               This will contain the final summary data from the end of the
95               test run.
96
97                   {
98                       # Was the test run a success, or were there failures?
99                       pass => $BOOL,
100
101                       # What tests failed?
102                       failed => [
103                           [
104                               $job_id,    # Job id of the job that failed
105                               $file,      # Test filename
106                           ],
107                           ...
108                       ],
109
110                       # What tests had to be retried, and did they eventually pass?
111                       retried => [
112                           [
113                               $job_id,            # Job id of the job that was retied
114                               $tries,             # Number of tries attempted
115                               $file,              # Test filename
116                               $eventually_passed, # 'YES' if it eventually passed, 'NO' if no try ever passed.
117                           ],
118                           ...
119                       ],
120
121                       # What tests setn a halt event (such as bail-out, or skip the rest)
122                       halted => [
123                           [
124                               $job_id,    # Job id of the test
125                               $file,      # Test filename
126                               $halt,      # Halt code
127                           ],
128                           ...
129                       ],
130
131                       # What tests were never run (maybe because of a bail-out, or an internal error)
132                       unseen => [
133                           [
134                               $job_id,    # Job id of the test
135                               $file,      # Test filename
136                           ],
137                           ...
138                       ],
139                   }
140
141           harness_watcher
142               Internal use only, subject to change, do not rely on it.
143
144           harness_job
145               A hash representation of an Test2::Harness::Runner::Job object.
146
147               Note: This is done via a transformation, several methods have
148               their values stored in this hash when the original object does
149               not directly store them.
150
151           harness_job_end
152                   {
153                       file     => $provided_path_to_test_file,
154                       rel_file => $relative_path_to_test_file,
155                       abs_file => $absolute_path_to_test_file,
156
157                       fail  => $BOOL,
158                       retry => $INTEGER,         # Number of retries left
159                       stamp => $UNIX_TIMESTAMP,  # Timestamp of when the test completed
160
161                       # May not be present
162                       skip  => $STRING,          # Reason test was skipped (if it was skipped)
163                       times => $TIMING_DATA,     # See below
164                   }
165
166               The "times" field is populated by calling data_dump() on an
167               Test2::Harness::Auditor::TimeTracker Object.
168
169           harness_job_exit
170               This represents when the test job exited.
171
172                   {
173                       exit  => $WSTAT,
174                       retry => $INTEGER
175                       stamp => $UNIX_TIMESTAMP
176                   }
177
178           harness_job_fields
179               Extra data attached to the harness job, usually from an
180               Test2::Harness::Plugin via inject_run_data().
181
182           harness_job_launch
183               This facet is almost always in the same event as the
184               "harness_job_start" facet. NOTE: While writing these docs the
185               author wonders if this facet is unnecessary...
186
187                   {
188                       stamp => $UNIX_TIMESTAMP,
189                       rety  => $INTEGER,
190                   }
191
192           harness_job_queued
193               This data is produced by the "queue_item" method in
194               Test2::Harness::TestFile.
195
196               This contains the data about a test job conveyed by the queue.
197               This usually contains data that will later be used by
198               Test2::Harness::Runner::Job. It is better to use the
199               "harness_job" facet, which contains the final data used to run
200               the job.
201
202               The following 3 fields are the only ones likely to be useful to
203               most people:
204
205                   {
206                       file   => $ORIGINAL_PATH_TO_FILE,
207                       job_id => $UUID_OR_STRING,
208                       stamp  => $UNIX_TIMESTAMP,
209                   }
210
211           harness_job_start
212               This facet is sent in an event as soon as a job starts. The
213               data in this facet is mainly intended to convey necessary
214               information to a renderer so that it can render the fact that a
215               job started.
216
217                   {
218                       file     => $provided_path_to_test_file,
219                       rel_file => $relative_path_to_test_file,
220                       abs_file => $absolute_path_to_test_file,
221
222                       stamp => $UNIX_TIMESTAMP,  # Timestamp of when the test completed
223                       job_id => $UUID_OR_STRING,
224
225                       details => "Job UUID_OR_STRING started at $UNIX_TIMESTAMP",
226                   }
227
228           harness_run
229               A hash representation of an Test2::Harness::Run object.
230

SOURCE

232       The source code repository for Test2-Harness can be found at
233       http://github.com/Test-More/Test2-Harness/.
234

MAINTAINERS

236       Chad Granum <exodist@cpan.org>
237

AUTHORS

239       Chad Granum <exodist@cpan.org>
240
242       Copyright 2020 Chad Granum <exodist7@gmail.com>.
243
244       This program is free software; you can redistribute it and/or modify it
245       under the same terms as Perl itself.
246
247       See http://dev.perl.org/licenses/
248
249
250
251perl v5.36.1                      2023-10-04            Test2::Harness::Log(3)
Impressum