docs/tests.pod

   1 # Copyright (C) 2001-2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/tests.pod - Testing Parrot
   7
   8 =head1 A basic guide to writing and running tests for Parrot
   9
  10 This is quick and dirty pointer to how the Parrot test suite is executed and
  11 to how new tests for Parrot should be written.
  12 The testing system is liable to change in the future, but tests written
  13 following the guidelines below should be easy to port into a new test suite.
  14
  15 =head1 How to test parrot
  16
  17 The easy way to test parrot is running C<make test>. If you have
  18 updated your code recently and tests began failing, go for a C<make
  19 realclean> and recompile parrot before complaining.
  20
  21 If your architecture supports JIT, you can test parrot JIT engine using C<make
  22 testj>. It works just like C<make test>, but uses the JIT engine when possible.
  23
  24 C<make languages-test> runs the test suite for most language implementations
  25 in the languages directory.
  26
  27 =head2 Submitting smolder test results
  28
  29 Parrot has a status page with smoke test results at
  30 L<http://smolder.plusthree.com/app/public_projects/details/8>.
  31
  32 You can supply new tests results by just running C<make smoke>.
  33 It will run the same tests as C<make test> would, but will upload
  34 the test results to the website.
  35
  36 =head1 Location of the test files
  37
  38 The parrot test files, the F<*.t> files, can be found in the F<t> directory.
  39 A quick overview over the subdirs in F<t> can be found in F<t/README>.
  40
  41 The language implementations usually have their test files in F<languages/*/t>.
  42
  43 New tests should be added to an existing F<*.t> file.
  44 If a previously untested feature is tested,
  45 it might also make sense to create a new F<*.t> file.
  46
  47 =head1 How to write a test
  48
  49 Test scripts must emit text that conforms to the C<Test Anything Protocol>.
  50 Test scripts are currently usually written in Perl 5 or PIR.
  51 The Perl 5 module C<Parrot::Test>
  52 and the PIR module C<Test;More> help with writing tests.
  53
  54 The testing framework needs to know how many tests it should expect.  So the
  55 number of planned tests needs to be incremented when adding a new test. This
  56 is done near the top of a test file, in a line that looks like:
  57
  58   use Parrot::Test tests => 8;
  59
  60 for Perl 5 based test scripts.
  61
  62 =head2 Testing Parrot Assembler
  63
  64 PASM tests are mostly used for testing ops.  Appropriate test files for basic
  65 ops are F<t/op/*.t>.  Polymorphic Containers are tested in F<t/pmc/*.t>.  Add the
  66 new test like this:
  67
  68     pasm_output_is(<<'CODE', <<'OUTPUT', "name for test");
  69         *** a big chunk of assembler, eg:
  70         print   1
  71         print   "\n" # you can even comment it if it's obscure
  72         end          # don't forget this...!
  73     CODE
  74     *** what you expect the output of the chunk to be, eg.
  75     1
  76     OUTPUT
  77
  78 =head2 Testing Parrot Intermediate Representation
  79
  80 Writing tests in B<PIR> is more convenient. This is done with
  81 C<pir_output_is> and friends.
  82
  83     pir_output_is(<<'CODE',<<'OUT','nothing useful');
  84         .sub main :main
  85             print "hi\n"
  86         .end
  87     CODE
  88     hi
  89     OUT
  90
  91 =head2 Testing C source
  92
  93 C source tests are usually located in F<t/src/*.t>.  A simple test looks like:
  94
  95     c_output_is(<<'CODE', <<'OUTPUT', "name for test");
  96     #include <stdio.h>
  97     #include "parrot/parrot.h"
  98     #include "parrot/embed.h"
  99
 100     static opcode_t *the_test(Parrot_Interp, opcode_t *, opcode_t *);
 101
 102     int main(int argc, char* argv[]) {
 103         Parrot_Interp interp;
 104         interpreter = Parrot_new(NULL);
 105
 106         if (!interpreter)
 107             return 1;
 108
 109         Parrot_run_native(interp, the_test);
 110         printf("done\n");
 111     fflush(stdout);
 112         return 0;
 113     }
 114
 115     static opcode_t*
 116     the_test(PARROT_INTERP,
 117         opcode_t *cur_op, opcode_t *start)
 118     {
 119         /* Your test goes here. */
 120
 121         return NULL;  /* always return NULL */
 122     }
 123     CODE
 124     # Anything that might be output prior to "done".
 125     done
 126     OUTPUT
 127
 128 Note that it's always a good idea to output "done" to confirm that the compiled
 129 code executed completely. When mixing C<printf> and C<Parrot_io_printf> always append
 130 a C<fflush(stdout);> after the former.
 131
 132 =head2 Testing Perl5 components
 133
 134 At the present time most, if not all, of the programs used to configure, build
 135 and install Parrot are written in Perl 5.  These programs take the form of
 136 program files (F<*.pl>) and Perl modules (F<*.pm>) holding subroutines and
 137 other variables imported into the program files.  Examples of such
 138 program files can be found under F<tools/>; examples of such Perl modules
 139 can be found under F<lib/Parrot/>.
 140
 141 All of these Perl 5 components ought to be tested.  Fortunately, over the last
 142 decade, under the leadership of Michael Schwern, chromatic, Andy Lester and
 143 many others, the Perl 5 community has developed a rigorous approach to testing
 144 in which:
 145
 146 =over 4
 147
 148 =item a
 149
 150 Subroutines found in F<*.pl> files are extracted and placed in F<*.pm>
 151 modules.
 152
 153 =item b
 154
 155 Those subroutines are then imported back into the program file.
 156
 157 =item c
 158
 159 Those subroutines are also imported into test files (F<*.t>) where are tests
 160 are run by Test::Builder-based modules such as Test::Simple and Test::More.
 161
 162 =item d
 163
 164 Those test files are run by Test::Harness-based functionality such as
 165 ExtUtils::MakeMaker's F<make test>, Module::Build's F<build test>, or
 166 Test::Harness's F<prove>.
 167
 168 =item e
 169
 170 The extent to which the test files exercise all statements in the Perl modules
 171 being tested is measured in coverage analysis using CPAN module Devel::Cover.
 172
 173 =item f
 174
 175 The underlying code is refactored and improved on the basis of the results of
 176 tests and coverage analysis.
 177
 178 =back
 179
 180 Tests reflecting this approach can be found in F<t/configure/>,
 181 F<t/postconfigure/>, F<t/tools/>, and so on.
 182
 183 It is our objective to test all Perl 5 components of the Parrot distribution
 184 using the methodology above.
 185
 186 =head3 Build Tools Tests
 187
 188 The files in F<t/postconfigure> are tests for build system. The build tools
 189 tests are intended to be run after someone has made changes in modules such as
 190 F<lib/Parrot/Pmc2cUtils/>, F<Ops2cUtils/> and F<Ops2pmutils/>.  They're set up
 191 to be run after F<Configure.pl> has completed but before make has been invoked.
 192 (In fact, they will generate errors if make has completed.)  You can run them
 193 with any of the following:
 194
 195      perl Configure.pl --test
 196      perl Configure.pl --test=build
 197      make buildtools_tests  (following Configure.pl)
 198
 199 =head2 Testing language implementations
 200
 201 Language implementations are usually tested with
 202 C<language_output_is> and friends.
 203
 204 =head1 Ideal tests:
 205
 206 =over 4
 207
 208 =item *
 209
 210 Probe the boundaries (including edge cases, errors thrown etc.) of whatever
 211 code they're testing.  These should include potentially out of band input
 212 unless we decide that compilers should check for this themselves.
 213
 214 =item *
 215
 216 Are small and self contained, so that if the tested feature breaks we can
 217 identify where and why quickly.
 218
 219 =item *
 220
 221 Are valid. Essentially, they should conform to the additional documentation
 222 that accompanies the feature (if any). [If there isn't any documentation, then
 223 feel free to add some and/or complain to the mailing list].
 224
 225 =item *
 226
 227 Are a chunk of assembler and a chunk of expected output.
 228
 229 =back
 230
 231 =head1 TODO tests
 232
 233 In test driven development, tests are implemented first.  So the tests are
 234 initially expected to fail.  This can be expressed by marking the tests as
 235 TODO. See L<Test::More> on how to do that.
 236
 237 =head1 SKIP tests
 238
 239 TODO test actually executed, so that unexpected success can be detected.
 240 In the case of missing requirements and in the case of serious breakdowns
 241 the execution of tests can be skipped.
 242 See L<Test::More> on how to do that.
 243
 244 =head1 SEE ALSO
 245
 246 L<http://qa.perl.org/>
 247 L<http://testanything.org/>
 248 L<http://en.wikipedia.org/wiki/Test_Anything_Protocol>
 249 F<t/TESTS.STATUS.pod>
 250 F<t/README>
 251
 252 =cut