t/README

   1 ===============================================================================
   2 |    ______                           ______                 __               |
   3 |  /\   __ \                         /\__  _\               _\ \__            |
   4 |  \ \  \/\ \ __  __  ______  ______ \/_/\ \/ ______  _____/\__  _\______     |
   5 |   \ \   __//\ \/\ \/\  __ \/\  ___\   \ \ \/\  ___\/\  ___\_/\ \/\  ___\    |
   6 |    \ \  \/ \ \ \_\ \ \ \/\ \ \___  \   \ \ \ \  ___\ \___  \\ \ \_\___  \   |
   7 |     \ \__\  \ \____/\ \____ \/\_____\   \ \_\ \_____\/\_____\\ \ _\\_____\  |
   8 |      \/__/   \/___/  \/___/\ \/____/     \/_/\/____/ \/____/  \/__//____/   |
   9 |                        /\____/                                              |
  10 |                        \/___/                                               |
  11 |                                                                             |
  12 ===============================================================================
  13
  14                      Welcome to the Pugs Test suite.
  15
  16 Pugs is currently being developed in a highly test-driven manner. Tests are
  17 written for both implemented and unimplemented features and are based roughly
  18 on the Perl6 Language Synopsis documents. All are welcome and encouraged to
  19 contribute to this test suite. The part under spec/ is considered to be the
  20 official Perl 6 test suite, and should only test what is specified in the
  21 Synopsis documents. It is also used by other Perl 6 implementations.
  22
  23 -------------------------------------------------------------------------------
  24 Getting Started
  25 -------------------------------------------------------------------------------
  26
  27 Here are some basic guidelines to help you get started writing tests for Pugs.
  28
  29 - Prerequisites
  30
  31 Please read the Perl 6 Spec first, namely, the Synopses:
  32
  33   http://perlcabal.org/syn/
  34
  35 or directly from the SVN repos:
  36
  37   http://svn.pugscode.org/pugs/docs/Perl6/Spec/
  38
  39 A good grasp of the Perl 6 language itself is very important to writing good
  40 tests.
  41
  42 - If you are unsure of something, don't hesitate to ask.
  43
  44 If you have a question about a test, written or unwritten, log on to #perl6 on
  45 irc.freenode.net or send an email to perl6-compiler and ask someone about it.
  46 If you have read the synopses very carefully and are still unsure about a
  47 perl6 language element, we encourage you to ask on #perl6 or email the
  48 perl6-language list and get clarification. Pugs and Perl 6 are group efforts
  49 and asking questions is a good thing.
  50
  51 - What to test
  52
  53 A number of Pugs hackers on #perl6 run regular smoke tests, and you can run
  54 your own using 'make smoke'. The smoke test produces an HTML graph of what tests
  55 are passing, and what aren't. This can be a good place to start. There's a smoke
  56 server on the web:
  57
  58   http://m19s28.dyndns.org/cgi-bin/pugs-smokeserv.pl?
  59
  60 There is also a cross linking which is made between the tests and the synopses.
  61 It's generated by running the 'util/smartlinks.pl' script. You
  62 can generate an HTML version of the latest Synopses cross-referenced with test
  63 file snippets from the test suite using the following command:
  64
  65     $ util/smartlinks.pl t/*/*.t t/*/*/*.t
  66
  67 There's a cross-referenced version of Synopses at
  68
  69     http://perlcabal.org/syn/
  70
  71 which is automatically updated by the smartlinks.pl script on feather once
  72 an hour.
  73
  74 - Use the Test module.
  75
  76 We have created a basic Test module found in ext/Test/lib/Test.pm. It is
  77 written in Perl 6 and implements the TAP protocol (and so can be used with
  78 Test::Harness). The module has its own documentation and I encourage you to
  79 read it.
  80
  81 - Pugs tests should have a non-she-bang line of "use v6;".
  82
  83 This line helps both Test::Harness as well as the 'prove6' utility when
  84 running Pugs tests.
  85
  86 - Place tests in the appropriate folder.
  87
  88 We have recently undergone a re-organization of the test suite in order to
  89 make it easier to find what has and has not been tested. It is important as
  90 the test suite grows that we try to keep this organization. If you have a test
  91 and are unsure of where to put it, ask on #perl6 for help, or put it in the
  92 general/ folder and email perl6-compiler and let us know.
  93
  94 Tests that belong to one synopsis document should go under
  95 t/spec/SXX-SECTION/, where XX is the number of the synopsis and SECTION is the
  96 title (or an important key word of the title) under which the tested behaviour
  97 is described.
  98
  99 Warning: please grep the whole test suite to ensure the tests you want to add
 100 are not already in some file.
 101
 102 - Run the test file with util/prove6 to test your tests.
 103
 104   util/prove6 t/foo/bar.t
 105
 106 Make sure the outputs are what you *can* expect even if your tests fail.
 107
 108 - If possible, please smart link your tests to the Synopsis
 109
 110 Smart links are explained in POD:
 111
 112   perldoc util/Text-SmartLinks/lib/Text/SmartLinks.pm
 113
 114 You may also find the following two pugs.blogs.com posts helpful:
 115
 116   http://pugs.blogs.com/pugs/2006/08/integrating_the.html
 117
 118   http://pugs.blogs.com/pugs/2006/09/check_smoke_res.html
 119
 120   http://pugs.blogs.com/pugs/2006/09/the_benefits_of.html
 121
 122 Everytime you have added smartlinks to some .t file, remember to run
 123 util/smartlinks.pl to verify the links' validity:
 124
 125    $ perl util/smartlinks.pl --check t/some/test.t
 126
 127 By default, the freshness of the synopses will be checked every time. Use
 128 "--fast" to skip that step.
 129
 130 - Dealing with parse failures
 131
 132 When developing tests for features that have not been implemented yet,
 133 often you find yourself writing code that doesn't compile. Don't get
 134 stuck on this: wrap the new code with eval and test it anyway. Just make
 135 sure that the test fails as long as the eval does, and until the feature
 136 has been implemented correctly.
 137
 138 Sometimes code is so futuristic, it can even confuse eval. We call this a
 139 "hard parsefail". When this happens, comment out the failing code, but mark
 140 it so it doesn't get forgotten, like this:
 141
 142     todo :pugs<6.28.0>, v6_pm<0.110>;
 143     flunk("FIXME parsefail");
 144     #ok eval('my code here');
 145
 146 Or another alternate style is as follows:
 147
 148     ok eval('# $code.which(%will, @fail)');
 149
 150     ok eval(q{
 151         blah blah blah
 152     });
 153
 154     is(eval(q{
 155         my $val;
 156         # some code here...
 157         $val;
 158     }), $expected, 'description');
 159
 160 which essentially comments out your eval, and returns 'undef' to ok().
 161
 162 - When TODO and when not TODO.
 163
 164 All of the functions in the Test module also have a 'todo' function. (See
 165 Test.pm's documentation for more details.)
 166
 167 The general rule about todo tests is that if the feature is not
 168 yet implemented, it is TODO. But if a feature is broken, or a bug is found
 169 then the tests should fail and *not* be TODO.
 170
 171 The only exception to this rule is that we TODO all failing tests before
 172 each point release. This is so 'make test' will succeed :)
 173
 174 Remember, the failing test *is* your bug report.
 175
 176 # vim: ft=text