tests/README

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