tests/README

   1 TODO: certain blocks are repeated over and over. For example, editing
   2 a page is always the same set of links to follow, but this info is
   3 duplicated across all test scripts. There should be a way of
   4 abstracting this info. Macros perhaps.
   5
   6 System requirements for the test suite for PhpWiki:
   7
   8 Sun's Java SDK  http://java.sun.com/j2se/
   9 httpunit        http://httpunit.sf.net
  10 Ant             http://jakarta.apache.org/builds/jakarta-ant/release/
  11 jtidy           http://sourceforge.net/project/showfiles.php?group_id=13153
  12
  13 (actually httpunit needs jtidy, not this test system per se)
  14 This was tested against Ant version 1.4.1 and httpunit 1.3.
  15
  16 ---
  17
  18 (This is just a set of entries from my work log when I was at Capital
  19 Thinking. It was then copy/pasted into their Wiki (they used PyWiki)
  20 as a little tutorial on how to use it. All of the basic information is
  21 here. It was tailor made for their system, so some reworking is still
  22 needed to make it work with PhpWiki; also I didn't quite grok unit
  23 testing as implemented by httpunit at the time. I suppose we'd also be
  24 better off using the PHP version of httpunit as well, though it was
  25 still beta when I last looked at it.
  26
  27 Capital Thinking uses ATG Dynamo on Solaris, so all of our work was in
  28 Java and Perl, in case you were wondering why these were chosen).
  29
  30 How to make a single test
  31 * write the script
  32 * generate the java file
  33 * compile it, run it
  34
  35 How to make a test suite:
  36 * write the script
  37 * run makemakebuild.pl
  38 * run ant
  39
  40 --------------
  41 Short Tutorial
  42
  43 The GuiTester is a small simple system to test the GUI of the BlueWire system.
  44
  45 As a programmer you have to do these steps:
  46
  47         1. Write a little input script. Let's call it MyTest.inputs.
  48         2. Create a Java source file with your input script, with a Perl script called maketest.pl. Run this command: '''maketest.pl MyTest.inputs'''. This will create a file called MyTest.java.
  49         3. Compile your file: '''javac MyTest.java'''
  50         4. Run your test: '''java MyTest'''
  51
  52 That's the short form for writing your own single test. You can accumulate tests in a single directory, and via the magical tools "make" and Ant, run a whole set of tests.
  53
  54         1. Write one or more input scripts.
  55         1. run '''makemakebuild.pl'''. This script gets the names of all .input files in the current directory and generates a Makefile and a build.xml file.
  56         1. Run ant with no arguments, i.e. just type "ant" and hit return.
  57
  58 That's all. All the Java files will be generated for you, compiled, and ran against BlueWire.
  59
  60
  61 -----------------
  62 A Longer Tutorial
  63
  64 An input script, which follows the naming convention ClassName.inputs,
  65 consists of a set of little statement blocks. Here is a sample which
  66 handles logging in to the system:
  67
  68  # start script
  69  # get the starting page
  70  type: starting_page
  71  start_url: http://127.0.0.1:8850/jpmorgan/index.jhtml
  72  go
  73
  74  # log in
  75  type: fill_and_submit_form
  76  form_num: 0
  77  submitbutton_num: 0
  78  setparam: "/jpmorgan/dbbeans/CTAuthentication.bean.username", "jpmorganuser"
  79  setparam: "/jpmorgan/dbbeans/CTAuthentication.bean.password", "jpmorganuser"
  80  assert_url: active_deals
  81  go
  82
  83  # end script
  84
  85 (If you use Emacs you can get some nice color highlighting with:
  86 M-x font-lock-mode RET
  87 M-x sh-mode RET)
  88
  89 First, each block starts with a type: command and ends with "go":
  90
  91  type: starting_page
  92  start_url: http://127.0.0.1:8850/jpmorgan/index.jhtml
  93  go
  94
  95 This tells the code generator the action we're taking ("type:") is
  96 going to the starting page, and "start_url:" has the URL to go to.
  97
  98 The second block will fill in and submit the form:
  99
 100  type: fill_and_submit_form
 101  form_num: 0
 102  submitbutton_num: 0
 103  setparam: "/jpmorgan/dbbeans/CTAuthentication.bean.username", "jpmorganuser"
 104  setparam: "/jpmorgan/dbbeans/CTAuthentication.bean.password", "jpmorganuser"
 105  assert_url: active_deals
 106  go
 107
 108 Here form_num is the form number in the page; that is, in
 109 Javascript-land, each form in the page has a number starting at
 110 zero. Likewise all submit buttons have a number (per form) starting at
 111 zero. "setparam" gives the name of the form field and the value for
 112 that field. Later we will see you can use names for the forms and
 113 submit buttons, if available.
 114
 115 Here's a list of the keywords in the little scripting language:
 116
 117  assert_field:
 118  assert_text:
 119  assert_title:
 120  assert_url:
 121  follow_image_link:
 122  follow_link:
 123  form_name:
 124  form_num:
 125  go
 126  setparam:
 127  start_url:
 128  submitbutton_name:
 129  submitbutton_num:
 130  type:
 131  #
 132
 133 -----
 134 '''Comments'''
 135
 136 Each comment has to be at the start of the line; you can introduce comments
 137 with a hash sign (#) at the start of a line:
 138
 139 # I am a comment.
 140
 141 oo-----
 142 '''Types of statement blocks'''
 143
 144 There are only four kinds of statement blocks in GuiTester:
 145
 146  starting_page
 147  fill_and_submit_form
 148  follow_image_link
 149  follow_link
 150
 151 They are pretty self explanatory. Any script you write will always
 152 start with the '''starting_page''' block. Usually this will be the
 153 index.jhtml of BlueWire and the second statement block will be
 154 '''fill_and_submit_form''' where you will log into the system.
 155
 156 -----
 157 '''Assertions'''
 158
 159 You can do assertions on form fields, titles, URLs and the text of the
 160 page. Assertions always follow the form:
 161
 162  assert_thing "string" <, "string">
 163
 164 Some assertions take one argument (title, URL, text) and one takes two
 165 (field). Examples:
 166
 167  assert_field: "fname", "Jackie"
 168  assert_field: "lname", "Robinson"
 169  assert_title: "this is the page's title"
 170  assert_url: "somedealpage.jhtml"
 171
 172 Assertions throw an exception and the test fails if they are not
 173 true. Assertions are always done after a page has been retrieved in a
 174 given statement block... this is a subtle point and you should reread
 175 that if it doesn't make sense. '''assert_url''' will take the string
 176 and try to match it in the URL returned.
 177
 178 -----
 179 '''Following links'''
 180
 181  follow_image_link:
 182  follow_link:
 183
 184 These will follow a link by the text in the link, or by the ALT text
 185 if it's an image link (like "Browse Deals").
 186
 187  follow_image_link: "Browse Deals"
 188  follow_link: "Get a Quick Quote"
 189
 190 -----
 191 '''Filling in forms'''
 192
 193  form_name:
 194  form_num:
 195  submitbutton_name:
 196  submitbutton_num:
 197  setparam:
 198
 199 These tell what form and what submit button to use... these are only
 200 used with '''fill_and_submit_form''' statement blocks. They take
 201 either a name (as shown in the '''name=""''' attribute of the form or
 202 button) or the number. The number is a Javascript/DOM thing; all forms
 203 are numbered by order of appearance starting at 0.
 204
 205 The '''setparam:''' directive will set a form field, and takes two
 206 arguments: the form field name, and the value. Note that you must
 207 always use double quotes for the arguments, separated by a comma:
 208
 209  setparam: "searchterm", "foo"
 210  setparam: "num_things", "3"
 211  setparam: "options_list", "16"