.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test2::Harness::Log 3pm" .TH Test2::Harness::Log 3pm "2023-03-12" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test2::Harness::Log \- Documentation about the Test2::Harness log file. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Test2::Harness aka App::Yath produces a rich/complete log when asked to do so. This module documents the log format. .SH "COMPRESSION" .IX Header "COMPRESSION" Test2::Harness can output log files uncompressed, compressed in gzip, or compressed in bzip2. .SH "FORMAT" .IX Header "FORMAT" The log file is in jsonl format. Each line of the log can be indepentantly parsed as json. Each line represents a single event Test2::Harness processed during a run. These events will be in the original order Test2::Harness processed them in (may not be chronological to when they were generated as generation, collection, processing, and rendering are handled in different processes. A complete log will be terminated by the string \f(CW\*(C`null\*(C'\fR, which is also valid json. If a log is missing this terminator it is considered an incomplete log. .SS "\s-1EVENTS\s0" .IX Subsection "EVENTS" \&\fBPlease note:\fR Older versions of Test2::Harness produced less complete events, this covers all current fields, if you are attempting to handle very old logs some of these fields may be missing. .PP Each event will have the following fields: .PP .Vb 6 \& { \& "event_id" : "CD01CD30\-D535\-11EA\-9B6A\-D90F9664FE12", \& "job_id" : 0, \& "job_try" : null, \& "run_id" : "CCF98E54\-D535\-11EA\-915A\-D70F9664FE12", \& "stamp" : 1596423763.76517, \& \& "facet_data" : { \& "harness" : { \& "event_id" : "CD01CD30\-D535\-11EA\-9B6A\-D90F9664FE12", \& "job_id" : 0, \& "job_try" : null, \& "run_id" : "CCF98E54\-D535\-11EA\-915A\-D70F9664FE12" \& }, \& \& ... \& } \& } .Ve .ie n .IP "event_id : ""\s-1UUID_OR_STRING""\s0" 4 .el .IP "event_id : ``\s-1UUID_OR_STRING''\s0" 4 .IX Item "event_id : UUID_OR_STRING" Typically this will be a \s-1UUID,\s0 but when UUIDs cannot be generated it may have a different unique identifier. This will always be a string. This may never be \&\s-1NULL,\s0 if it is \s-1NULL\s0 then that is a bug and should be reported. .ie n .IP "job_id : ""0_OR_UUID_OR_STRING""" 4 .el .IP "job_id : ``0_OR_UUID_OR_STRING''" 4 .IX Item "job_id : 0_OR_UUID_OR_STRING" \&\s-1ID\s0 \f(CW0\fR is special in that it represents the test harness itself, and not an actual test being run. Normally the job_id will be a \s-1UUID,\s0 but may be another unique string if \s-1UUID\s0 generation is disabled or not available. .IP "job_try : \s-1INTEGER_OR_NULL\s0" 4 .IX Item "job_try : INTEGER_OR_NULL" For \f(CW\*(C`job_id => 0\*(C'\fR this will be \f(CW\*(C`NULL\*(C'\fR for any other job this will be an intgeger of 0 or greater. This is 0 for the first time a test job is run, if a job is re-run due to failure (or any other reason) this will be incremented to tell you what run it is. When a job is re-run it keeps the same job \s-1ID,\s0 you can use this to distinguish events from each run of the job. .ie n .IP "run_id : ""\s-1UUID_OR_STRING""\s0" 4 .el .IP "run_id : ``\s-1UUID_OR_STRING''\s0" 4 .IX Item "run_id : UUID_OR_STRING" This is the run_id of the entire yath test run. This should be the same for every event in any given log. .IP "stamp : \s-1UNIX_TIME_STAMP\s0" 4 .IX Item "stamp : UNIX_TIME_STAMP" Timestamp of the event. This is \s-1NORMALLY\s0 set when an event is generated, however if an event does not have its own time stamp yath will give it a timestamp upon collection. Events without timestamps happen if the test outputs \&\s-1TAP\s0 instead of Test2::Event objects, or if a tool misbehaves in some way. .IP "facet_data : \s-1HASH\s0" 4 .IX Item "facet_data : HASH" This contains all the the data of the event, such as if an assertion was made, what file name and line number generated it, etc. .Sp In addition to the original facets of the event, Test2::Harness may inject the following facets (or generate completely new events to convey these facets). .RS 4 .IP "harness_final" 4 .IX Item "harness_final" This will contain the final summary data from the end of the test run. .Sp .Vb 3 \& { \& # Was the test run a success, or were there failures? \& pass => $BOOL, \& \& # What tests failed? \& failed => [ \& [ \& $job_id, # Job id of the job that failed \& $file, # Test filename \& ], \& ... \& ], \& \& # What tests had to be retried, and did they eventually pass? \& retried => [ \& [ \& $job_id, # Job id of the job that was retied \& $tries, # Number of tries attempted \& $file, # Test filename \& $eventually_passed, # \*(AqYES\*(Aq if it eventually passed, \*(AqNO\*(Aq if no try ever passed. \& ], \& ... \& ], \& \& # What tests setn a halt event (such as bail\-out, or skip the rest) \& halted => [ \& [ \& $job_id, # Job id of the test \& $file, # Test filename \& $halt, # Halt code \& ], \& ... \& ], \& \& # What tests were never run (maybe because of a bail\-out, or an internal error) \& unseen => [ \& [ \& $job_id, # Job id of the test \& $file, # Test filename \& ], \& ... \& ], \& } .Ve .IP "harness_watcher" 4 .IX Item "harness_watcher" Internal use only, subject to change, do not rely on it. .IP "harness_job" 4 .IX Item "harness_job" A hash representation of an Test2::Harness::Runner::Job object. .Sp \&\fBNote:\fR This is done via a transformation, several methods have their values stored in this hash when the original object does not directly store them. .IP "harness_job_end" 4 .IX Item "harness_job_end" .Vb 4 \& { \& file => $provided_path_to_test_file, \& rel_file => $relative_path_to_test_file, \& abs_file => $absolute_path_to_test_file, \& \& fail => $BOOL, \& retry => $INTEGER, # Number of retries left \& stamp => $UNIX_TIMESTAMP, # Timestamp of when the test completed \& \& # May not be present \& skip => $STRING, # Reason test was skipped (if it was skipped) \& times => $TIMING_DATA, # See below \& } .Ve .Sp The \f(CW\*(C`times\*(C'\fR field is populated by calling \f(CW\*(C`data_dump()\*(C'\fR on an Test2::Harness::Auditor::TimeTracker Object. .IP "harness_job_exit" 4 .IX Item "harness_job_exit" This represents when the test job exited. .Sp .Vb 5 \& { \& exit => $WSTAT, \& retry => $INTEGER \& stamp => $UNIX_TIMESTAMP \& } .Ve .IP "harness_job_fields" 4 .IX Item "harness_job_fields" Extra data attached to the harness job, usually from an Test2::Harness::Plugin via \f(CW\*(C`inject_run_data()\*(C'\fR. .IP "harness_job_launch" 4 .IX Item "harness_job_launch" This facet is almost always in the same event as the \f(CW\*(C`harness_job_start\*(C'\fR facet. \fI\s-1NOTE:\s0\fR While writing these docs the author wonders if this facet is unnecessary... .Sp .Vb 4 \& { \& stamp => $UNIX_TIMESTAMP, \& rety => $INTEGER, \& } .Ve .IP "harness_job_queued" 4 .IX Item "harness_job_queued" This data is produced by the \f(CW\*(C`queue_item\*(C'\fR method in Test2::Harness::TestFile. .Sp This contains the data about a test job conveyed by the queue. This usually contains data that will later be used by Test2::Harness::Runner::Job. It is better to use the \f(CW\*(C`harness_job\*(C'\fR facet, which contains the final data used to run the job. .Sp The following 3 fields are the only ones likely to be useful to most people: .Sp .Vb 5 \& { \& file => $ORIGINAL_PATH_TO_FILE, \& job_id => $UUID_OR_STRING, \& stamp => $UNIX_TIMESTAMP, \& } .Ve .IP "harness_job_start" 4 .IX Item "harness_job_start" This facet is sent in an event as soon as a job starts. The data in this facet is mainly intended to convey necessary information to a renderer so that it can render the fact that a job started. .Sp .Vb 4 \& { \& file => $provided_path_to_test_file, \& rel_file => $relative_path_to_test_file, \& abs_file => $absolute_path_to_test_file, \& \& stamp => $UNIX_TIMESTAMP, # Timestamp of when the test completed \& job_id => $UUID_OR_STRING, \& \& details => "Job UUID_OR_STRING started at $UNIX_TIMESTAMP", \& } .Ve .IP "harness_run" 4 .IX Item "harness_run" A hash representation of an Test2::Harness::Run object. .RE .RS 4 .RE .SH "SOURCE" .IX Header "SOURCE" The source code repository for Test2\-Harness can be found at \&\fIhttp://github.com/Test\-More/Test2\-Harness/\fR. .SH "MAINTAINERS" .IX Header "MAINTAINERS" .IP "Chad Granum " 4 .IX Item "Chad Granum " .SH "AUTHORS" .IX Header "AUTHORS" .PD 0 .IP "Chad Granum " 4 .IX Item "Chad Granum " .PD .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2020 Chad Granum . .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See \fIhttp://dev.perl.org/licenses/\fR