swete User Documentation

Security Note

Do not run swete_proxy on any computer exposed to the internet or on an untrusted network. swete_proxy acts as a server and will therefore accept connections from remote computers. The software has not been evaluated for resistance to intrusion.

Contents

1. Download the appropriate binary archive and extract it to the directory of your choice:
   
   Windows (not currently available): Double click on the downloaded self extracting archive
   Linux (in an empty directory): tar -xzf swete-redhat-el-0.1.tar.gz
2. Place the directory containing the binary files into your systems execution path (optional). [Windows 2000 How To] [Red Hat How To]
3. If you plan to use the <normalize_content> element, ensure that sed is installed in the system path.

Instructions for compiling the program from scratch are provided in the Developer Documentation

Usage: swete_proxy -p=port [-d=directory -o -c=file_name -s=server -r -h]
Usage: swete_proxy --port=port [--directory=directory -o --continue=file_name --server=server -r -h]

Note: The following examples assumes the directory containing the swete executables has been placed in the systems execution path.

1. Open a console window (on Windows: Start -> Run "Command" or "CMD" [OK]).
2. Create and switch to the directory in which you record the script; for example (on windows):
   mkdir \test_directory
   cd \test_directory
3. Type:
   swete_proxy --port 8888 (or any other valid port number)
   or
   swete_proxy -p 8888 (or any other valid port number)
   Note that the --port (-p) option is mandatory and requires exactly one argument (the port number).
4. If necessary, stop your web browser to clear any session cookies.
5. Start a web browser and then configure it to use swete_proxy as it's proxy server [Internet Explorer How To] [Mozilla How To].
6. Clear your browser's cache [Internet Explorer How To] [Mozilla How To].
7. Browse the website you would like test.
8. When you have finished browsing all of the pages you would like to test, make sure the console window in which swete_proxy is active and type [ctrl] c
9. The script was recorded in the file swete_script.xml
10. Reconfigure the web browser to its' original internet connection settings.

Using the --help (-h) Option

The --help option prints out a brief explanation of the available command line options. For example:
swete_proxy --help
or
swete_proxy -h

Using the --directory (-d) Option

Use the --directory option to specify the directory in which to place the recorded script. This option requires exactly one argument (the directory name). For example:
swete_proxy --port 8888 --directory \test_directory
or
swete_proxy -p 8888 -d \test_directory

Using the --overwrite (-o) Option

swete_proxy will not run if the current working directory or the directory specified using the --directory option already contains a swete_script.xml file. Use the --overwrite option to tell swete_proxy to overwrite the swete_script.xml file and any external response_*.htm files present in the directory. For example:
swete_proxy --port 8888 --directory \test_directory --overwrite
or
swete_proxy -p 8888 -d \test_directory -o

The --continue option plays back an existing swete_script.xml file to the specified point, and then allows you to continue recording the script from that point. Any requests in the swete_script.xml file after the specified point will be replaced by the newly recorded requests. For example:
swete_proxy --port 8888 --directory \test_directory --continue response_6.htm
or
swete_proxy -p 8888 -d \test_directory -c response_6.htm

The --server and --replace options may be used in combination with the --continue option. Their usage is described below.

Please note that it is not necessary to use the --continue option to update a script if the only changes are to page content that does not affect POST data or the sequencing of subsequent pages. See Modifying Test Scripts (below) for more information.

Usage: swete_test [-d=ARG -s=ARG -r -i -h]
Usage: swete_test [--directory=directory --server=server --replace --ignore --help]

Use swete_test to play back previously recorded test scripts. Each response received from the server is compared with those received when the script was recorded. Swete_test can ignore expected differences between the actual server response and the response recorded in the script (see Modifying Test Scripts below).

Using the --help (-h) Option

The --help option prints out a brief explanation of the available command line options. For example:
swete_test --help
or
swete_test -h

Using the --directory (-d) Option

Use the --directory option to specify the directory in which to find the recorded script. This option requires exactly one argument (the directory name). For example:
swete_test --directory \test_directory
or
swete_test -d \test_directory

Use the --server option to specify a server to send the requests to. This will override the server recorded in the test script. This option requires exactly one argument in the format hostname:port. The :port is optional (default port is :80). For example:
swete_test --server myhost:8888
or
swete_test -s myhost

Using the --ignore (-i) Option

Instruct swete_test to continue testing after receiving unexpected differences between the server response and the expected response recorded in test script. The default behavior is to abandon the test after an unexpected response is received. For example:
swete_test --ignore
or
swete_test -i

This option may be useful if the text of a header or footer has been modified changing the output for every page in the script but leaving the overall page sequence unchanged. In this case, run swete_test with the -i option, and then copy the resulting unexpected_response_*.htm files over the corresponding response_*.htm files (after verifying they in fact contain the revised content).

Please note test execution will terminate upon detection of scripting errors (i.e. the file swete_script.xml does not conform with the schema) even if the --ignore option was selected.

Instruct swete_test to replace the values of hidden input elements recorded in the test script with those received from the server in the previous request (during the playback session). For example:
swete_test --replace
or
swete_test -r

Use this option if hidden inputs contain values that are expected to vary from session to session.

Updated Expected Response Files

It is not necessary to re-record a test script if the expected response(s) of the web application change such that POST data and the overall page sequence remain the same (e.g. minor wording or formatting differences on a page). In this case, use the following procedure:

1. Verify that the file(s) containing the unexpected server response(s) (e.g. unexpected_response_8.htm) contains the proper output
2. Move th unexpected server response file to the corresponding response file. For example (on Windows):
   move unexpected_response_8.htm response_8.htm
   or, if you are daring:
   move unexpected_response_*.htm response_*.htm
3. It may also be necessary to adjust the values of any expected differences specified in the swete_script.xml file (e.g. <ignore_text> and <todays_date_location> elements).

Specifying Expected Differences

Some web applications generate pages that contain text that is expected to vary from run to run (e.g. todays date or a real time stock quote). It is possible to modify the swete_script.xml file recorded by swete_proxy to instruct swete_test to ignore these expected differences.

The <normalize_content pattern="RegExp"> element will cause swete_test to ignore any differences in all content that matches the Regular Expression given by the pattern attribute. As indicated in the schema, zero or more of these elements may be placed at the beginning of the <swete_script> element. The scope of <normalize_content> declarations includes all scripts that execute after the declaration has been processed. Note that this feature requires that sed be in the system's execution path.

Another way to address expected differences between the response obtained at script creation time and the response at testing time is to specify the differences at the request level. For example, if the page content contained the following table element:

<td>9-13-2004</td>

with the character '9' occuring at the 2504th character of the response file (response_5.htm) and we expected the date received from the server to be the date the test was run (todays date), we could add the following element to swete_script.xml after the </raw_response> element:

If the date is always a fixed number of days (3 in the example below) in the future, use:

The list of valid format values is contained in the schema. How to determine the proper value for first_character? Change the first digit of the date in the expected response file and then rerun swete_test (without the -i option). Swete_test will output the location of the first difference between the expected and actual server response (which you just created by changing the expected response file).

swete_test will now ignore any differences starting at the '$' character until just before the first occurence of the string </td> in the response. But wait, aren't we ignoring the one piece of information on the page we most want to be correct? Unfortunately, yes. In this circumstance, the best swete_test can do (currently) is test the rest of the page content and overall page sequence. Use a another tool (e.g. getest) to verify that the function which generates the ignored text is doing so properly.

Combining Tests

It is possible to execute another swete_script test from within a swete_script file. For example, if we want to execute the test contained in the subdirectory "test_2" after receiving response_5.htm, we would add the following element to swete_script.xml:

or

<call_script directory /> runs the new script as a new session (new cookies, etc.), whereas <include_script directory /> runs the script as a continuation of the existing session.

A swete_script.xml file may contain zero or more request elements and zero or more call_script elements in any order; but it should contain at least one of one or the other.

• Error handling (especially schema error handling) is pretty much untested.
• Persistent cookies are not supported; domain, path and secure options for cookies are not supported.
• The swete_test --replace option may not work properly if a hidden input value contains the name of another input in the request.
• The swete_test --replace option may not work if the a hidden input with the same name has different values during a session and [(1) The session includes re-posting of previously submitted form data (i.e. use the browser's back button to resubmit a previously submitted form; or (2) A pop-up window window is opened using javascript after a form is presented to the user and before the form is submitted to the server.]
• The swete_proxy --continue option may leave orphan response_*.htm files cluttering up the test directory (but these files will not impact the performance of the tests).

Introduction to swete

Developer Information

Source Forge Project Page (for downloads, support, feature requests, mailing lists, cvs access, etc.)