Front page | perl.bootstrap |
Postings from July 2000
In One Sentence
---------------
Regression tests should be embedded in the code and documentation near what
it is they're testing.
Synopsis
--------
It's an old rule of thumb that documentation should be near the code it's
documenting. This increases the likelyhood that the docs will be kept up to
date with the code. This is one of the reasons we have POD. Building on
that idea is that tests should also be near what it is testing. This
involves embedding tests in the documentation.
The implementation can be very simple. Just add a =test directive to POD.
For example:
=item B<is_pirate>
@pirates = is_pirate(@arrrgs);
Go through @arrrgs and return a list of pirates.
=test
my @p = is_pirate('Blargbeard', 'Alfonse', 'Capt. Hampton', 'Wesley');
@p == 2;
=cut
sub is_pirate {
...
}
=test would be treated as a code block and the last evaluated expression
During configuration the =test blocks can be cut out of the source code and
a regression test file built to be run during "make test" along with the
traditional t/*.t files.
Problems
--------
There are issues of initialization and scope to be delt with when smashing
all these tests together, but I believe that'll be solved during
implementation.
Embedded tests might not be appropriate for large, complicated tests which
is why t/ and .t files will be kept around. The two will co-exist. In
fact, the embedded tests can simply generate a .t file and run along with
the other tests.
If Makemaker is made aware, regular Perl code can also use =test.
Pod::Parser could be made aware and a Pod::Test module written. "=for test"
is an interesting alternative POD tag, this would allow embedded tests to be
added to perl5 and perl5 modules.
Spin-offs
---------
As noted, this is useful for things outside of perl6 internals. Once
Pod::Test is written it can very easily be retrofitted to both perl5,
Makemaker and independently added to module Makefile.PLs and any existing
Perl code!
Things to do NOW
----------------
- A prototype version of Pod::Test will be written to note "=test" and "=for
test" POD tags, and build .t file(s). [Any takers?]
- A simple example of adding Pod::Test to a Makefile.PL would be nice.
[Any takers?]
- It may be needed/wanted to alter Pod::Parser to recognize =test/=for test.
- Embedded regression tests can be added to the existing code of perl5. The
t/ directory can be trolled for tests which can be embedded and the docs
and code read to write simple embedded tests. The perl5 POD reader (the
thing which builds perlapi and friends) would have to be modified to
understand =test (or =for test). Pod::Test could be used.
Blame
-----
All blame for embedded tests, =test and =for test can be transfered to
Michael G Schwern <schwern@pobox.com>
--
Michael G Schwern http://www.pobox.com/~schwern/ schwern@pobox.com
Just Another Stupid Consultant Perl6 Kwalitee Ashuranse
Maybe they hooked you up with one of those ass-making magazines.
-- brian d. foy as misheard by Michael G Schwern