TAP::Diagnostics

Ovid on 2007-09-01T11:40:09

In future versions of TAP, YAML is intended for embedded diagnostic information. There's been a lot of discussion about what should be done, but no code written. Therefore, I've started on a new module named TAP::Diagnostics. The intent is to have test module authors use this and if the "new-style TAP" is used, to include YAML diagnostic information. Note that all of this is 100% backwards compatible. Old style TAP parsers will ignore information it does not recognize (a feature added in version 5 of TAP back in 1996).

Here's what I currently have, based on thoughts from Adrian Howard, Schwern, Andy Armstrong and my own imagination:

A stub module named "TAP::Diagnostics". I currently have three poorly named functions.

is_new_tap()

The author of a test module can call this to find out if new-style TAP diagnostics are supported. This is done internally by checking the TAP_VERSION environment variable. This might get internalized in the following two functions (though it shouldn't matter if indented YAML is encountered by older TAP parsers. It just means that running tests in verbose mode will spit out more info).

  diagnostic( {
    found   => $found,   # can be stand-alone
    wanted  => $wanted,  # must always be present with 'found'
    display => $display, # optional human-readable presentation
    extra   => $extra,   # anything else. Useful for custom harnesses
    meta    => 0,
  } );

The 'meta' information defaults to true but can be suppressed. Currently this allows the line number and filename to be inserted into the TAP.

  meta()

This spits out meta information for the current test program. Currently looks like this:

     ---
     executable: perl
     inc:
       - lib
       - t/lib
       - /System/Library/Perl/5.8.6/darwin-thread-multi-2level
       - /System/Library/Perl/5.8.6
       - /Library/Perl/5.8.6/darwin-thread-multi-2level
       - /Library/Perl/5.8.6
       - /Library/Perl
       - /Network/Library/Perl/5.8.6/darwin-thread-multi-2level
       - /Network/Library/Perl/5.8.6
       - /Network/Library/Perl
       - /System/Library/Perl/Extras/5.8.6/darwin-thread-multi-2level
       - /System/Library/Perl/Extras/5.8.6
       - /Library/Perl/5.8.1
       - .
     os: darwin
     perl: 5.008006
     tap_version: 13
     ...

Some of that is Perl-specific and therefore is wrong. However, it can be very useful for debugging information.

This won't be immediately useful to most people, but it means that we'll be able to create diagnostic objects which enhanced harnesses can use to provide richer information to people. If Schwern is willing, a patch to Test::Simple will ensure that many people will be able to start using this fairly quickly.

Comments and suggestions welcome.