t/README

   1
   2
   3   Writing Tests
   4   =============
   5
   6   Here's how to write tests.
   7
   8   1. Create a new file in the t directory, called foo.t. Start with
   9      the following lines:
  10
  11         require 't/test.pl';
  12         package OddMuse;
  13         use Test::More tests => $num
  14         clear_pages();
  15
  16      This will load the testing library, make all its functions
  17      available to you, announce that you plan to make $num tests, and
  18      clear all the pages from the test wiki.
  19
  20      The test wiki will be created in /tmp/oddmuse.
  21
  22   2. The wiki is accessed via the command line only. You don't need to
  23      have your code installed on a webserver! Just run the test from
  24      the parent directory:
  25
  26         perl t/foo.t
  27
  28   3. Write $num tests. :)
  29
  30   4. To examine the situation after having run some tests, you can
  31      also call the script from the command line. The only problem is
  32      that the tests use a specific data directory that you need to
  33      provide via an environment variable:
  34
  35         WikiDataDir=test-data perl wiki.pl action=index raw=1
  36
  37   add_module, remove_module, and remove_rule
  38   ------------------------------------------
  39
  40   Load a module before you run any tests:
  41
  42     add_module('usemod.pl');
  43
  44   If the module has important setup code, you might have to add the
  45   following:
  46
  47     InitVariables();
  48
  49   The reason is this: If you add a module and the run the script
  50   again, you're fine. But if you run tests that don't invoke another
  51   copy of the script, then the init code will not have run.
  52
  53   Modules and rules need rarely be removed, since every *.t file
  54   starts in a new process.  If you then want to run additional tests
  55   without the module you added (in the same *.t file!), then remove
  56   both the module and the rules it added. You'll have to do this
  57   manually, unfortunately.
  58
  59     remove_module('usemod.pl');
  60     remove_rule(\&UsemodRule);
  61
  62
  63
  64   update_page
  65   -----------
  66
  67     $page = update_page($pagename, $content);
  68     update_page($pagename, $content, $summary, $minor, $admin, @rest);
  69
  70   @rest is a list of parameter=value string pairs:
  71
  72     @rest = ('username=joe', 'ns=Moore');
  73
  74   If updating the page resultet in a redirect, the redirect is stored
  75   in the variable $redirect, and you still get the result page
  76   returned.
  77
  78     test_page($redirect, split('\n',<<'EOT'));
  79     banned text
  80     wiki administrator
  81     matched
  82     See .*BannedContent.* for more information
  83     EOT
  84
  85   You can even create pages containing file uploads directly:
  86
  87     $page = update_page('alex pic', "#FILE image/png\niVBORw0KGgoAAAA");
  88
  89
  90   get_page
  91   --------
  92
  93     $page = get_page('action=calendar');
  94     $page = get_page('action=rc all=1 showedit=1');
  95     $page = get_page('action=rc', 'all=1', 'showedit=1');
  96     test_page(get_page('action=all'),
  97               'restricted to administrators');
  98
  99   Return the text of the page. The parameters are the parameters
 100   available to you from the command line when using the CGI library:
 101
 102     keyword1 keyword2 keyword3
 103     keyword1+keyword2+keyword3
 104     name1=value1 name2=value2
 105     name1=value1&name2=value2
 106     "name1='I am a long value'" "name2=two\ words"
 107     /your/path/here?name1=value1&name2=value2
 108
 109
 110
 111   run_tests
 112   ---------
 113
 114   Takes a list of alternating input and output strings, applies rules
 115   (and thus @MyRules) to input and compares it to the output. If you
 116   have html attributes in the output you want to test, use
 117   xpath_run_tests, because the order of the attributes is not
 118   guaranteed and varies with CGI library version.
 119
 120     run_tests(q{"Get lost!", they say.},
 121               q{&#x201c;Get lost!&#x201d;, they say.});
 122
 123     run_tests(split('\n', <<'EOT'));
 124     input1
 125     output1
 126     input2
 127     output2
 128     EOT
 129
 130   Newline excapes \n in the input and output are translated to real
 131   newlines when running the tests.
 132
 133     run_tests(split('\n',<<'EOT'));
 134     * ''one\n** two
 135     <ul><li><em>one</em><ul><li>two</li></ul></li></ul>
 136     EOT
 137
 138
 139
 140   test_page and test_page_negative
 141   --------------------------------
 142
 143   Tests any string for regular expression matches:
 144
 145     test_page($string, $regexp1, $regexp2, ...);
 146     test_page(update_page($pagename, $content), $re1, $re2);
 147
 148   Or make sure that none of the regular expressions match:
 149
 150     test_page_negative($page,
 151                        "rollback",
 152                        "Rollback",
 153                        "EvilPage",
 154                        "AnotherEvilPage",
 155                       );
 156
 157
 158
 159   xpath_run_tests
 160   ---------------
 161
 162   This is the equivalent of run_tests using XPath instead of simple
 163   string comparison.  It takes a list of alternating input and xpath
 164   tests, applies rules (and thus @MyRules) to the input and applies
 165   the test to the output.
 166
 167     xpath_run_tests(split('\n',<<'EOT'));
 168     WikiWord
 169     //a[@class="edit"][@title="Click to edit this page"]
 170     This is a [:day for fun and laughter].
 171     //a[@class="anchor"][@name="day_for_fun_and_laughter"]
 172     EOT
 173
 174   XPath is harder to write, but is ideal when the output contains tags
 175   with more than one attribute, since the order of attributes is
 176   undefined. And you don't even have to test for all the attributes.
 177
 178
 179
 180   xpath_test and negative_xpath_test
 181   ----------------------------------
 182
 183   The equivalent of test_page, but using xpath instead of exact
 184   matches.
 185
 186
 187     xpath_test(get_page('action=all pwd=foo'),
 188              '//p/a[@href="#HomePage"][text()="HomePage"]',
 189              '//h1/a[@name="foo"][text()="foo"]',
 190              '//a[@class="local"][@href="#bar"][text()="bar"]',
 191              '//h1/a[@name="bar"][text()="bar"]')
 192
 193   And the same thing for negative matches, of course:
 194
 195     negative_xpath_test($page, '//h1/a[not(text())]');
 196
 197
 198   run_macro_tests
 199   ---------------
 200
 201     run_macro_tests(split('\n',<<'EOT'));
 202     $input1
 203     $output2
 204     $input2
 205     $output2
 206     EOT
 207
 208   Tests @MyMacros.
 209
 210