docs/tests.pod

   1 # Copyright (C) 2001-2006, 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 The testing framework needs to know how many tests it should expect.  So the
  56 number of planned tests needs to be incremented when adding a new test. This
  57 is done near the top of a test file, in a line that looks like:
  58
  59   use Parrot::Test tests => 8;
  60
  61 =head2 Parrot Assembler
  62
  63 PASM tests are mostly used for testing ops.  Appropriate test files for basic
  64 ops are F<t/op/*.t>.  Perl Magic Cookies are tested in F<t/pmc/*.t>.  Add the
  65 new test like this:
  66
  67     pasm_output_is(<<'CODE', <<'OUTPUT', "name for test");
  68         *** a big chunk of assembler, eg:
  69         print   1
  70         print   "\n" # you can even comment it if it's obscure
  71         end          # don't forget this...!
  72     CODE
  73     *** what you expect the output of the chunk to be, eg.
  74     1
  75     OUTPUT
  76
  77 =head2 Parrot Intermediate Representation
  78
  79 Writing tests in B<PIR> is more convenient. This is done with
  80 C<pir_output_is> and friends.
  81
  82     pir_output_is(<<'CODE',<<'OUT','nothing useful');
  83         .include 'library/config.pir'
  84
  85         .sub main :main
  86             print "hi\n"
  87         .end
  88     CODE
  89     hi
  90     OUT
  91
  92 =head2 C source tests
  93
  94 C source tests are usually located in F<t/src/*.t>.  A simple test looks like:
  95
  96     c_output_is(<<'CODE', <<'OUTPUT', "name for test");
  97     #include <stdio.h>
  98     #include "parrot/parrot.h"
  99     #include "parrot/embed.h"
 100
 101     static opcode_t *the_test(Parrot_Interp, opcode_t *, opcode_t *);
 102
 103     int main(int argc, char* argv[]) {
 104         Parrot_Interp interpreter;
 105         interpreter = Parrot_new(NULL);
 106
 107         if (!interpreter)
 108             return 1;
 109
 110         Parrot_run_native(interpreter, the_test);
 111         printf("done\n");
 112     fflush(stdout);
 113         return 0;
 114     }
 115
 116     static opcode_t*
 117     the_test(Parrot_Interp interpreter,
 118         opcode_t *cur_op, opcode_t *start)
 119     {
 120         /* Your test goes here. */
 121
 122         return NULL;  /* always return NULL */
 123     }
 124     CODE
 125     # Anything that might be output prior to "done".
 126     done
 127     OUTPUT
 128
 129 Note that it's always a good idea to output "done" to confirm that the compiled
 130 code executed completely. When mixing C<printf> and C<PIO_printf> always append
 131 a C<fflush(stdout);> after the former.
 132
 133 =head2 Test Perl5 helpers
 134
 135 Perl5 unit tests are in F<t/perl/*.t>.
 136
 137 =head2 Testing language implementations
 138
 139 Language implementations are usually tested with
 140 C<language_output_is> and friends..
 141
 142 =head1 Ideal tests:
 143
 144 =over 4
 145
 146 =item *
 147
 148 Probe the boundaries (including edge cases, errors thrown etc.) of whatever
 149 code they're testing.  These should include potentially out of band input
 150 unless we decide that compilers should check for this themselves.
 151
 152 =item *
 153
 154 Are small and self contained, so that if the tested feature breaks we can
 155 identify where and why quickly.
 156
 157 =item *
 158
 159 Are valid. Essentially, they should conform to the additional documentation
 160 that accompanies the feature (if any). [If there isn't any documentation, then
 161 feel free to add some and/or complain to the mailing list].
 162
 163 =item *
 164
 165 Are a chunk of assembler and a chunk of expected output.
 166
 167 =back
 168
 169 =head1 TODO tests
 170
 171 In test driven development, tests are implemented first.  So the tests are
 172 initially expected to fail.  This can be expressed by marking the tests as
 173 TODO. See L<Test::More> on how to do that.
 174
 175 =head1 SKIP tests
 176
 177 TODO test actually executed, so that unexpected success can be detected.
 178 In the case of missing requirements and in the case of serious breakdowns
 179 the execution of tests can be skipped.
 180 See L<Test::More> on how to do that.
 181
 182 =head1 SEE ALSO
 183
 184 L<http://qa.perl.org/>
 185 F<t/TESTS.STATUS.pod>
 186 F<t/README>
 187
 188 =cut