NAME

Test2::Harness::Fact - Representation of an event or output line from a test.

DESCRIPTION

Test2 generates events. Events are encapsulated by Test2::Event objects. Unfortunately a harness must be able to handle output beyond what the events handle. A fact is an abstraction of an even or line of output from the test. This includes data such as what filehandle it came from, what the output line that generated it looked like, etc.

Some producers are able to send entire Test2::Event objects, in which case the original object can be retrieved from the fact.

ATTRIBUTES

All of these can be provided as construction arguments. You can also call set_ATTR(...) for any attribute to set a value.

$ts = $f->stamp

Timestamp from fact creation.

$summary = $f->summary

A human-readable summary of the event. If this is not provided one will be generated.

$int = $f->nested

This will be an integer representing how deeply nested a fact is (IE subtests).

This will be -1 for the fact containing the final Test2::Harness::Result object. It will be 0 for any root-level event or subtest. This will be 1 for events inside a subtest, 2 for a nested subtest, etc.

It is also valid for this to be undefined, in which case it should be treated as a 0.

$bool = $f->diagnostics

True if the event should be displayed even in non-verbose mode for diagnostics purposes.

$bool = $f->causes_fail

True if the fact results in a failure. (Example: 'not ok')

$bool = $f->increments_count

True if the fact adds to the test count.

$plan_ref = $f->sets_plan()

This will be undefined unless the fact sets the plan. The plan is returned as a 3 element array:

    [$expected_test_count, $directive, $reason]

$directive and $reason are typically undefined, but will be present in cases such as skip-all.

$id = $f->in_subtest()

If the fact is inside a subtest then this will have a unique identifier for the subtest. The unique identifier is arbitrary and parser specific.

$id = $f->is_subtest()

If the fact is a final subtest result this will contain a unqiue identifier for it. The unique identifier is arbitrary and parser specific.

$code = $f->terminate()

If the fact resulted in the test file terminating then this will be populated with an integer exit value.

$int = $f->number()

If the fact incremented the test count this will have the test number. For other facts this will either contain the last test number seen, or it will be undefined.

$bool = $f->hide()

True if the renderers should hide the event. (This is for IPC events not intended for humans to see).

$bool = $f->start()

This is true if the fact represents the test file being started.

$e = $f->event

This is true if the fact was likely created because of an Test2::Event object. Depending on the parser this could be a simple boolean, or it could be a fully reconstructed Test2::Event object, or a hash of fields from the event object.

True/False is the only part of the return you can trust to always be available.

$error = $f->parse_error

This will be set to the error string if the fact is the result of a parser error.

$text = $f->output

This will be set if the fact was produced directyl from a line of STDERR or STDOUT.

$enc = $f->encoding

Set if this fact is intended to set the encoding.

$f->parser_select

This will be set to the name of the parser upon parser selection.

$line = $f->parsed_from_string

If the fact was produced from a line of output the original line will be here.

$name = $f->parsed_from_handle

This will typically return 'STDERR' or 'STDOUT'. This can be undefined if the fact was not produced from a line of output.

METHODS

$json = $f->to_json

Convert the fact to JSON.

$f = Test2::Harness::Fact->from_string($str, %overrides)

Construct a fact from a string:

    T2_EVENT: ...JSON DATA...

$f = Test2::Harness::Fact->from_json($json, %overrides)

Construct an event from JSON data.

$f = Test2::Harness::Fact->from_event($event, %overrides)

Construct a fact from an Test2::Event object.

$f = Test2::Harness::Fact->from_result($result, %overrides)

Construct a fact from an Test2::Harness::Result 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 2016 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/