Test::Builder - *DISCOURAGED* Module for building testing libraries.
This module was previously the base module for almost any testing library. This module is now little more than a compatability wrapper around Test::Stream. If you are looking to write or update a testing library you should look at Test::Stream::Toolset.
However if you must support older versions of Test-Simple/More/Builder then you MUST use this module for your testing code.
The variable that holds the Test::Builder singleton. It is best practice to leave this variable alone, messing with it can have unexpected consequences.
In the past this variable was used to track stack depth so that Test::Builder could report the correct line number. If you use Test::Builder this will still work, but in new code it is better to use the Test::Stream::Context module unless you must support older versions of Test-Simple.
Returns the singleton stored in $Test::Builder::Test.
$Test::Builder::Test
Returns a new instance of Test::Builder. It is important to note that this instance will not use the shared Test::Stream::Hub object unless you pass in the use_shared => 1 argument.
use_shared => 1
This is a way to get a new instance of Test::Builder that is not the singleton. This is usually done for testing code.
Helper method for Test::Builder to get a Test::Stream::Context object. This is primarily for internal use, and is NOT present on older versions of Test::Builder.
Get the subtest depth. If this is called inside a subtest the value will be 1.
This is a way to find and/or set the TODO reason. This method has complex and unintuitive logic, it is kept for legacy reasons, but it is recommended that you not use it.
Calling with no arguments it will try to find the $TODO variable for you and return the value.
Calling with a package will try to find the $TODO value of that package.
If you include $set and $new_value it will set the $TODO variable for the specified package.
This will return true if TODO is set, false otherwise.
This finds the todo message currently set, if any. If you specify a package it will look there unless it finds a message set in the singleton.
This will try to find the details about where the test was called.
Warn from the perspective of the test caller.
Throw an exception from the perspective of the test caller.
DISCOURAGED
This used to be used internally to start a subtest. Subtests started in this way must call finalize() when they are done.
finalize()
Use of this method never gained traction, and was never strictly necessary. It has always been better to use the subtest() method instead which handles the hard work for you. This is too low level for most use cases.
subtest()
Use this to end a subtest created via child().
child()
Interface to Data::Dumper that dumps whatever you give it. This is really just a quick way to dump human readable test of structures.
Test::Builder used to assume that tests would only ever be run from a single package, usually main. This is a way to tell Test::Builder what package is running tests. This assumption proved to be very dumb.
It is not uncommon to have tests run from many packages, as a result this method is pretty useless if not actively harmful. Almost nothing uses this, but it has been preserved for legacy modules.
Check if something is a filehandile.
Get/Set $Test::Builder::Level. $Level is a package var, and most things localize it, so this method is pretty useless.
$Test::Builder::Level
Check if something might be a regex. These days we have qr// and other things that may make this method seem silly, however in older versions of perl we did not have such luxuries. This method exists for old code and environments where strings may be used as regexes.
qr//
Reset the builder object to a very basic and default state. You almost certainly do not need this unless you are writing a tool to test testing libraries. Even then you probably do not want this.
In newer code using Test::Stream this completely resets the state in the shared hub as well.
Set a todo message. This will make all results 'TODO' if they are generated after this is set.
Unset the TODO message.
In older versions of Test::Builder these methods directly effected the singleton. These days they are all compatability wrappers around Test::Stream. If possible you should use Test::Stream, however if you need to support older versions of Test::Builder these will work fine for both.
These allow you to get and/or set the filehandle for various types of output. Note that this will not effect UTF8 or other encodings that are specified using the Test::Stream interface. This only effects the 'legacy' encoding used by Test::Stream by default.
This will reset all the outputs to the default. Note this only effects the 'legacy' encoding used by Test::Stream.
Do not display Test::Stream::Event::Diag events.
Do not do some special magic at the end that tells you what went wrong with tests.
Do not display the plan.
Turn numbers in TAP on and off.
Get all the events that occured on this object. Each event will be transformed into a hash that matches the legacy output of this method.
Set/Get expected number of tests
Check if there is a plan
List of pass/fail results.
Get/Set the current test number. Setting the test number is probably not something you want to do, except when validating testing tools.
This is a way to check if the test suite is currently passing or failing.
See Test::Stream::Context, Test::Stream::Toolset, and Test::More::Tools. Calling the methods below is not advised.
These will issue an Test::Stream::Event::Bail event. This will cause the test file to stop running immedietly with a message. In TAP this event is ALSO a signal to the harness to abort any remaining testing.
$TB->cmp_ok('foo', 'eq', 'foo', 'check that foo is foo');
Check that a comparison of $type is true for the given values.
$type
$TB->diag("This is a diagnostic message");
This will print a message, typically to STDERR. This message will get a '# ' prefix so that TAP harnesses see it as a comment.
This will issue an Test::Stream::Event::Plan event. This plan will set the expected number of tests to the current test count. This will also tell Test::Stream that the test should be done.
If you provide an argument, that argument will be used as the expected number of tests.
This will issue an Test::Stream::Event::Ok event. If $got matches $expect the test will pass, otherwise it will fail. This method expects values to be strings.
This will issue an Test::Stream::Event::Ok event. If $got matches $expect the test will pass, otherwise it will fail. This method expects values to be numerical.
This will issue an Test::Stream::Event::Ok event. If $got matches $dont_expect the test will fail, otherwise it will pass. This method expects values to be strings.
This will issue an Test::Stream::Event::Ok event. If $got matches $dont_expect the test will fail, otherwise it will pass. This method expects values to be numerical.
This will check $thing against the $regex. If it matches the test will pass.
This will check $thing against the $regex. If it matches the test will fail.
This tells Test::Builder that there should be no plan, and that is the plan.
Send a message to STDOUT, it will be prefixed with '# ' so that TAP harnesses will see it as a comment.
Issues an Test::Stream::Event::Ok event. If $bool is true the test passes, otherwise it fails.
Set the number of tests that should be run.
Skip all the tests for the specified reason. $reason is a string.
The plan is that there is no plan.
Skip a single test for the specified reason. This generates a single Test::Stream::Event::Ok event.
Skip all the tests for the specified reason.
Run the provided codeblock as a subtest. All results will be indented, and all that matters is the final OK.
Skip a single test with a todo message. This generates a single Test::Stream::Event::Ok event, it will have both it's 'todo' and its 'skip' set to $reason.
Get the hub used by this builder (or the shared hub). This is not available on older test builders.
Name of the test builder instance, this is only useful inside a subtest.
Parent builder instance, if this is a child.
Many legacy testing modules monkeypatch ok(), plan(), and others. The abillity to monkeypatch these to effect all events of the specified type is now considered discouraged. For backwords compatability monkeypatching continues to work, however in the distant future it will be removed. Test::Stream upon which Test::Builder is now built, provides hooks and API's for doing everything that previously required monkeypatching.
ok()
plan()
The original Test::Tutorial. Uses comedy to introduce you to testing from scratch.
The Test::Tutorial::WritingTests tutorial takes a more technical approach. The idea behind this tutorial is to give you a technical introduction to testing that can easily be used as a reference. This is for people who say "Just tell me how to do it, and quickly!".
The Test::Tutorial::WritingTools tutorial is an introduction to writing testing tools that play nicely with other Test::Stream and Test::Builder based tools. This is what you should look at if you want to write Test::MyWidget.
The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.
The following people have all contributed to the Test-More dist (sorted using VIM's sort function).
There has been a lot of code migration between modules, here are all the original copyrights together:
Copyright 2015 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://www.perl.com/perl/misc/Artistic.html
Originally authored by Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua Pritikin's Test module and lots of help from Barrie Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.
Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern <schwern@pobox.com>, wardrobe by Calvin Klein.
Copyright 2001-2008 by Michael G Schwern <schwern@pobox.com>.
To the extent possible under law, 唐鳳 has waived all copyright and related or neighboring rights to Test-use-ok.
This work is published from Taiwan.
http://creativecommons.org/publicdomain/zero/1.0
This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts are based on other people's work.
Under the same license as Perl itself
Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004.
To install Test::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Simple
CPAN shell
perl -MCPAN -e shell install Test::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.