23 Jan 2021 22:44:04 UTC
- Distribution: Test-Inline
- Module version: 2.214
- Source (raw)
- Browse (raw)
- How to Contribute
- Issues (21)
- Testers (288 / 7 / 0)
- KwaliteeBus factor: 1
- 80.03% Coverage
- License: perl_5
- Perl: v5.6.0
- Activity24 month
- Download (58.99KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest version++ed by:1 non-PAUSE userETHER Karen Etheridge 🐾 🌋🦑🇹🇼🇭🇰🇺🇦
- Reverse dependencies
- CPAN Testers List
- Dependency graph
Take me over?The maintainer of this distribution is looking for someone to take over! If you're interested then please contact them via email.
- TO DO
- COPYRIGHT AND LICENSE
Test::Inline - Embed your tests in your code, next to what is being tested
Embedding tests allows tests to be placed near the code being tested.
This is a nice supplement to the traditional .t files.
Test::Inlinelets you write small fragments of general or function-specific testing code, and insert it anywhere you want in your modules, inside a specific tagged POD segment, like the following.
=begin testing # This code assumes we have a cpuinfo file ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' ); =end testing =begin testing label # Test generation of the <label> HTML tag is( My::HTML->label('foo'), '<label>foo</label>', '->label(simple) works' ); is( My::HTML->label('bar', 'foo'), '<label for="bar">foo</label>', '->label(for) works' ); =end testing
You can add as many, or as few, of these chunks of tests as you wish. The key condition when writing them is that they should be logically independant of each other. Each chunk of testing code should not die or crash if it is run before or after another chunk.
These test scripts can then be executed as normal.
Test::Inlineis incredibly useful for doing ad-hoc unit testing.
In any large groups of modules, you can add testing code here, there and everywhere, anywhere you want. The next time the test compiler is run, a new test script will just appear.
This also makes it great for testing assumptions you normally wouldn't bother to write run-time code to test. It ensures that your assumptions about the way Perl does some operation, or about the state of the host, are confirmed at install-time.
If your assumption is ever wrong, it gets picked up at install-time and based on the test failures, you can correct your assumption.
It's also extremely useful for systematically testing self-contained code.
That is, any code which can be independantly tested without the need for external systems such as databases, and that has no side-effects on external systems.
All of this code, written by multiple people, can then have one single set of test files generated. You can check all the bits and pieces of a large API, or anything you like, in fine detail.
Test::Inline also introduces the concept of unit-tested documentation.
Not only can your code be tested, but if you have a FAQ or some other pure documentation module, you can validate that the documentation is correct for the version of the module installed.
If the module ever changes to break the documentation, you can catch it and correct the documentation.
Test::Inlineis not a complete testing solution, and there are several types of testing you probably DON'T want to use it for.
Static testing across the entire codebase
Tests with side-effects such as those that might change a testing database
Because Test::Inline creates test scripts with file names that don't start with a number (for ordering purposes), the first step is to create your normal test scripts using file names in the CPAN style of 01_compile.t, 02_main.t, 03_foobar.t, and so on.
You can then add your testing fragments wherever you like throughout your code, and use the inline2test script to generate the test scripts for the inline tests. By default the test scripts will be named after the packages/classes that the test fragments are found in.
Tests for Class::Name will end up in the file
These test files sit quite happily alongside your number test scripts.
When you run the test suite as you normally would, the inline scripts will be run after the numbered tests.
my $Tests = Test::Inline->new( verbose => 1, readonly => 1, output => 'auto', manifest => 'auto/manifest', );
newconstructor creates a new test generation framework. Once the constructor has been used to create the generator, the
add_classmethod can be used to specify classes, or class heirachies, to generate tests for.
verbose - The
verboseoption causes the generator to write state and debugging information to STDOUT as it runs.
manifest - The
manifestoption, if provided, will cause a manifest file to be created and written to disk. The manifest file contains a list of all the test files generated, but listed in the prefered order they should be processed to best satisfy the class-level dependency of the tests.
check_count - The
check_countvalue controls how strictly the test script will watch the number of tests that have been executed.
When set to false, the script does no count checking other than the standard total count for scripts (where all section counts are known)
When set to
Test::Inlinedoes smart count checking, doing section-by-section checking for known-count sections only when the total for the entire script is not known.
When set to
Test::Inlinedoes full count checking, doing section-by-section checking for every section with a known number of tests.
file_content - The
file_contentoption should be provided as a CODE reference, which will be passed as arguments the
Test::Inlineobject, and a single Test::Inline::Script object, and should return a string containing the contents of the resulting test file. This will be written to the
output - The
outputoption provides the location of the directory where the tests will be written to. It should both already exist, and be writable. If using a custom
OutputHandler, the value of
outputshould refer to the location within the OutputHandler that the files will be written to.
readonly - The
readonlyoption, if provided, indicates that any generated test files should be created (or set when updated) with read-only permissions, to prevent accidentally adding to or editing the test scripts directly (instead of via the classes).
This option is currently disabled by default, by may be enabled by default in a future release, so if you do NOT want your tests being created as read-only, you should explicitly set this option to false.
InputHandler - The
InputHandleroption, if provided, supplies an alternative
FileHandlerfrom which source modules are retrieved.
OuputHandler - The
OutputHandleroption, if provided, supplies an alternative
FileHandlerto which the resulting test scripts are written.
Returns a new
Test::Inlineobject on success.
undefif there is a problem with one of the options.
exceptionmethod returns a flag which indicates whether error will be returned via exceptions.
InputHandlermethod returns the file handler object that will be used to find and load the source code.
ExtractHandleraccessor returns the object that will be used to extract the test sections from the source code.
ContentHandleraccessor return the script content generation handler.
OutputHandleraccessor returns the file handler object that the generated test scripts will be written to.
addmethod is a parameter-sensitive method for adding something to the build schedule.
It takes as argument a file path, a directory path, a reference to a SCALAR containing perl code, or an IO::Handle (or subclass) object. It will retrieve code from the parameter as appropriate, parse it, and create zero or more Test::Inline::Script objects representing the test scripts that will be generated for that source code.
Returns the number of test scripts added, which could be zero, or
$Tests->add_class( 'Foo::Bar' ); $Tests->add_class( 'Foo::Bar', recursive => 1 );
add_classmethod adds a class to the list of those to have their tests generated. Optionally, the
recursiveoption can be provided to add not just the class you provide, but all classes below it as well.
Returns the number of classes found with inline tests, and added, including
0if no classes with tests are found. Returns
undefif an error occurs while adding the class or it's children.
add_allmethod will search the
InputHandlerfor all *.pm files, and add them to the generation set.
Returns the total number of test scripts added, which may be zero, or
classesmethod returns a list of the names of all the classes that have been added to the
Test::Inlineobject, or the null list
()if nothing has been added.
For a given class name, fetches the Test::Inline::Script object for that class, if it has been added to the
undefif the class has not been added to the
For all of the classes added, the
filenamesmethod generates a map of the filenames that the test files for the various classes should be written to.
Returns a reference to a hash with the classes as keys, and filenames as values.
0if there are no files to write.
filenamesmethod generates a map of the files for the various classes, the
schedulereturns the list of file names in the order in which they should actually be executed.
Returns a reference to an array containing the file names as strings.
0if there are no files to write.
manifestgenerates the contents of the manifest file, if it is both wanted and needed.
Returns the contents of the manifest file as a normal string, false if it is either not wanted or needed, or
savemethod generates the test files for all classes, and saves them to the
Returns the number of test files generated. Returns
- Add support for
- Add support for
Thank you to Phase N (http://phase-n.com/) for permitting the open sourcing and release of this distribution.
The "Extended =begin" syntax used for non-trivial sections is not formalised as part of the POD spec yet, although it is on the track to being included.
While simple '=begin testing' sections are fine and will pass POD testing, extended begin sections may cause POD errors.
Adam Kennedy <email@example.com>
Adam Kennedy <firstname.lastname@example.org>
Karen Etheridge <email@example.com>
Ricardo Signes <firstname.lastname@example.org>
This software is copyright (c) 2003 by Adam Kennedy.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.