Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test2::Harness::Log(3)User Contributed Perl DocumentatioTest2::Harness::Log(3)

NAME
       Test2::Harness::Log - Documentation about the Test2::Harness log	file.

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

COMPRESSION
       Test2::Harness can output log files uncompressed, compressed in gzip,
       or compressed in	bzip2.

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 "null", which is also
       valid json. If a	log is missing this terminator it is considered	an
       incomplete log.

   EVENTS
       Please note: 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.

       Each event will have the	following fields:

	   {
	      "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"
		 },

		 ...
	      }
	   }

       event_id	: "UUID_OR_STRING"
	   Typically this will be a UUID, but when UUIDs cannot	be generated
	   it may have a different unique identifier. This will	always be a
	   string. This	may never be NULL, if it is NULL then that is a	bug
	   and should be reported.

       job_id :	"0_OR_UUID_OR_STRING"
	   ID 0	is special in that it represents the test harness itself, and
	   not an actual test being run. Normally the job_id will be a UUID,
	   but may be another unique string if UUID generation is disabled or
	   not available.

       job_try : INTEGER_OR_NULL
	   For "job_id => 0" this will be "NULL" 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	ID, you	can use	this to	distinguish
	   events from each run	of the job.

       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.

       stamp : UNIX_TIME_STAMP
	   Timestamp of	the event. This	is NORMALLY 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 TAP instead of	Test2::Event
	   objects, or if a tool misbehaves in some way.

       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.

	   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).

	   harness_final
	       This will contain the final summary data	from the end of	the
	       test run.

		   {
		       # 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, # 'YES' if it eventually passed, 'NO' 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
			   ],
			   ...
		       ],
		   }

	   harness_watcher
	       Internal	use only, subject to change, do	not rely on it.

	   harness_job
	       A hash representation of	an Test2::Harness::Runner::Job object.

	       Note: This is done via a	transformation,	several	methods	have
	       their values stored in this hash	when the original object does
	       not directly store them.

	   harness_job_end
		   {
		       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
		   }

	       The "times" field is populated by calling "data_dump()" on an
	       Test2::Harness::Auditor::TimeTracker Object.

	   harness_job_exit
	       This represents when the	test job exited.

		   {
		       exit  =>	$WSTAT,
		       retry =>	$INTEGER
		       stamp =>	$UNIX_TIMESTAMP
		   }

	   harness_job_fields
	       Extra data attached to the harness job, usually from an
	       Test2::Harness::Plugin via "inject_run_data()".

	   harness_job_launch
	       This facet is almost always in the same event as	the
	       "harness_job_start" facet. NOTE:	While writing these docs the
	       author wonders if this facet is unnecessary...

		   {
		       stamp =>	$UNIX_TIMESTAMP,
		       rety  =>	$INTEGER,
		   }

	   harness_job_queued
	       This data is produced by	the "queue_item" method	in
	       Test2::Harness::TestFile.

	       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
	       "harness_job" facet, which contains the final data used to run
	       the job.

	       The following 3 fields are the only ones	likely to be useful to
	       most people:

		   {
		       file   => $ORIGINAL_PATH_TO_FILE,
		       job_id => $UUID_OR_STRING,
		       stamp  => $UNIX_TIMESTAMP,
		   }

	   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.

		   {
		       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",
		   }

	   harness_run
	       A hash representation of	an Test2::Harness::Run object.

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

MAINTAINERS
       Chad Granum <exodist@cpan.org>

AUTHORS
       Chad Granum <exodist@cpan.org>

COPYRIGHT
       Copyright 2020 Chad Granum <exodist7@gmail.com>.

       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/

perl v5.32.1			  2020-11-18		Test2::Harness::Log(3)

NAME | DESCRIPTION | COMPRESSION | FORMAT | SOURCE | MAINTAINERS | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test2::Harness::Log&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help