t/HOWTO

   1 =head1 How to add tests to the test suite
   2
   3 This is a guide on how to add tests to the official Perl 6 test suite.
   4
   5 =head2 Pro Forma
   6
   7 All file paths in this directory are relative to the root of the pugs
   8 repository (unless stated otherwise). You can obtain the pugs SVN repository
   9 by typing
  10
  11    svn co http://svn.pugscode.org/pugs
  12
  13 A file path C<t/spec/> is the directory that can be obtained from
  14 C<http://svn.pugscode.org/pugs/t/spec/>.
  15
  16 The test suite lives in C<t/>, and is slowly being moved to C<t/spec/>
  17
  18 =head2 Where to start?
  19
  20 First pick a language feature you want to test. If you don't know what to test
  21 and just want to test something, look at the file F<t/TASKS>, it contains a
  22 list of stuff that needs testing.
  23
  24 =head2 Check the other tests first
  25
  26 Many things are already tested, and it would be waste of time to duplicate the
  27 effort, and a maintenance burden. So first check if there are tests for the
  28 things you want. Usually a very efficient method is to do a full text search
  29 on the current test suite, either with C<grep> or C<ack> (a perl replacement
  30 for grep, see L<http://search.cpan.org/dist/ack>).
  31
  32 Suppose you want to know if the method C<pick> is already implemented. You'd
  33 go into C<t/> and then type:
  34
  35     $ ack -l '\bpick\b'
  36     examples/99problems/problem80.t
  37     examples/99problems/problem24.t
  38     examples/99problems/problem25.t
  39     examples/99problems/problem23.t
  40     spec/fudge
  41     spec/S03-junctions/misc.t
  42     spec/fudgeall
  43     spec/S03-operators/assign.t
  44     spec/S29-list/pick.t
  45     junction/junction_any_pick.t
  46     junction/junction_functions.t
  47     junction/junction_pick.t
  48
  49 Anything that doesn't end in C<.t> can be ignored for now. You see that there
  50 are even files with C<pick> in their name, so you can be pretty sure it's
  51 already tested.
  52
  53 If you didn't find any tests, or the existing ones aren't covering all cases,
  54 go on with the next step.
  55
  56 =head2 Where to Put the Tests?
  57
  58 If there are already similar tests to those you want to add, just put them
  59 into the same file.
  60
  61 If you're writing completely new tests, find a spot below C<t/spec/> where it
  62 fits.
  63
  64 The typical file name of a test is C<t/spec/S29-list/map.t>. C<S29> is
  65 the synopsis where the feature is described, it can be found at
  66 L<http://perlcabal.org/syn/S29.html>. C<list> is the section within S29 where
  67 the feature is described, and C<map> is the feature being tested.
  68
  69 Please adhere to this style as good as possible, when you are in doubt, ask on
  70 #perl6 on irc.freenode.org. Words in test file names should be separated by
  71 hyphens, eg C<S99-weird/very-weird-features.t>.
  72
  73 =head2 Write the Tests
  74
  75 The test suite uses the "Test Anything Protocol" (short TAP), and a module
  76 named C<Test> that produces the appropriate output. Perl 5 programmers will
  77 be familiar with it because it's very much like L<Test::More>.
  78
  79 Suppose you'd want to test the power operator C<**>. Your test file might
  80 be looking something like this:
  81
  82     use v6;
  83     use Test;
  84     plan 4;
  85
  86     is 2**4,    16, 'Can calculate power of integers';
  87     is (-2)**3, -8, 'Can calculate power of negative integers';
  88     is_approx 2**0.5, sqrt(2), 'Can use fractional exponents';
  89     is 0**30,    0, '0**$something is 0 again';
  90
  91 Let's go through this line by line.
  92
  93 The first line tells the compiler that it is
  94 a Perl 6 source file, not Perl 5. The second one loads the C<Test> module.
  95
  96 C<plan 4;> says "we're planning to run 4 tests in this file". If for example
  97 the test silently dies during execution, the TAP parser knows how many tests
  98 you planned to run, and raises an error if it didn't run that many.
  99
 100 The next line is our first real test. It calls the C<is()> function with three
 101 arguments: the first is the expression whose value is being tested (C<2**4>),
 102 the second is the expected value (C<16>), and the third is a short description
 103 of what the test does.
 104
 105 The next three lines are similar in spirit. Note that the third test uses
 106 C<is_approx> instead of C<is>, because it deals with floating point values,
 107 and direct comparison of floating point values is nearly always wrong.
 108
 109 =head2 Smartlinks
 110
 111 The test suite uses so-called "smartlinks" to identify which test files cover
 112 which parts of the synopsis. Please add at least one smartlink to each test
 113 file that you write.
 114
 115 Smart links are covered in more detail here:
 116
 117     http://pugs.blogs.com/pugs/2006/08/integrating_the.html
 118     http://pugs.blogs.com/pugs/2006/09/check_smoke_res.html
 119     http://pugs.blogs.com/pugs/2006/09/the_benefits_of.html
 120
 121 C<t/README> also contains some information on how smartlinks work.
 122
 123 In our example we'd go into C<docs/Perl6/Spec> where the synopsis live, and
 124 search for occurrences of C<**>:
 125
 126     ack -Q '**'
 127
 128 This returns many results. The ones from C<Rule.pod> are mostly unrelated
 129 to the operator we just tested, because C<Rule.pod> describes regular
 130 expressions, and C<**> has a different meaning there.
 131
 132 The best match seems to be C<Operator.pod>. Looking at
 133 L<http://perlcabal.org/syn/> reveals that it's also called S03 for short. So
 134 we know that our smartlink will start with C<< L<S03/> >>. Next we find out
 135 which section the best match is. That's C<Exponentiation precedence> in our
 136 case, so our smartlink looks like this:
 137 C<< L<S03/Exponentiation precedence/> >>.
 138
 139 The only thing missing is to identify the paragraph. Instead of copying
 140 the markup, we just use a part of what will be displayed, and put it
 141 in double quotes:
 142 C<< L<S03/Exponentiation precedence/"infix:<**>"> >>. We place that line
 143 directly after the C<plan> directive in our test file.
 144
 145 =head2 Committing your changes
 146
 147 Once you've written (or edited) a reasonable test file, you should commit the
 148 changes to the pugs repository.
 149 If you don't have a commit bit (that is the power to commit changes to the
 150 repository) join #perl on irc.freenode.net and ask for one.
 151
 152 If you merely edited a test file, a simple
 153 C<svn ci> will do:
 154
 155     svn ci -m '[t/spec] added tests for $frobnicate_feature' path/to/file.t
 156
 157 If you created a new file, you have to call C<svn add> first and set the svn
 158 properties. Lazy programmers use a shell script for that:
 159
 160     ./util/add-text-file.sh t/spec/S99-weird/very-weird-features.t
 161     svn ci -m '[t/spec] test for very weird features' t/spec/S99-weird/very-weird-features.t
 162
 163 Please always include the C<[t/spec]> marker at the beginning of your commit
 164 messages (or C<[t]> if you didn't modify C<t/spec/>), it helps others to
 165 identify which part of the repository you changed.
 166
 167 =cut
 168
 169 # vim: ft=pod