Re: HOWTO: Writing Perl6 Tests (was: Project Start: Section 1)

"Sean O'Rourke" <[email protected]> wrote > languages/perl6/t/*/*.t is
what we've got, though they're intended to
> exercise the prototype compiler, not the "real language" (which looks like
> it's changing quite a bit from what's implemented).

OK, lets take a specific test. builtins/array.t contains a test for the
reverse (array) function. Ignoring the fact that it is obviously incomplete,
I'd like to focus on the format of the test.

The test currently looks like (with a bit of cleanup):

#!perl
use strict;
use P6C::TestCompiler tests => 1;
##############################
output_is(<<'CODE', <<'OUT', "reverse");
sub main() {
        @array = ("perl6", "is", "fun");
        print @array, "\n";
        print reverse @array;
        print "\n", @array, "\n";
}
CODE
perl6isfun
funisperl6
perl6isfun
OUT
##############################

This is fine as a test, but not as documentation. Furthermore, it is
depending on the "print" statement for its comparison (not necessarily bad;
but I find that "golden-output" style tests tend to become difficult to
maintain -- specific assertions tend to work better).

So what would documentation for this feature look like?

=context array ops
=function reverse
The reverse functions takes an existing array, and returns a new array that
contains the same elements in the reverse order. Like all functions on
arrays, it can also be called as a method on the array, using "dot"
notation. The following example demonstrates its use:

=test simple_array_reverse
my @original = qw( foo bar baz );
my @result = reverse @original;

assert_equal( @result, qw( baz bar foo ) );
assert_equal( @original, qw( foo bar baz ) );

my @reversed_again = @result.reverse;
assert_equal( @reversed_again, qw( foo bar baz ) );
=test-end

=cut

I'm not claiming that the test is any better. But its context is that of
documentation, not code. An obvious question is how to extend it to be a
more thorough test, whilst not spoiling the documentation. We'd want to
intersperse text with the test-code; and probably mark a few bits as
"hidden", from a normal documentation view (levels of hiding might be
defined for overview vs. reference vs. guru levels of understanding).


Dave.