docs/tests.pod

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