tests/README

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