tests/README

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