top bar top logo bar top bar
left design right design
spacer bar

WebInject Manual


More tools by Corey Goldberg:  www.goldb.org
Subscribe To Corey's Blog Subscribe To Goldblog

Table of Contents









1 - Software Architecture

1.1 - Architecture Diagram


architecture

1.2 - Summary

WebInject consists of the WebInject Engine (test runner) and an optional User Interface (GUI). The WebInject Engine can be run on its own from the command line, or called from the GUI.

2 - Configuration

2.1 - Configuration File (config.xml)

There is a configuration file named 'config.xml' that is used to store configuration settings for your project. You can use this to specify which test case files to run (see below) and to set some constants and settings to be used by WebInject.

If you use WebInject in console mode, you can specify an alternate config file name by using the option -c or --config. See the "Command Line Options" section of this manual for more information.

All settings and constants must be enclosed in the proper tags, and simply need to be added to the config.xml file (order does not matter).

Available config settings are:

proxy

Specifies a proxy server to route all HTTP requests through.

example:
<proxy>http://127.0.0.1:8080</proxy>

You can also do proxy authentication like this:

example:
<proxy>http://username:password@127.0.0.1:8080</proxy>

useragent

Specifies a User-Agent string to be sent in outgoing HTTP headers. If this setting is not used, the default User-Agent string sent is "WebInject". A User-Agent string is how each request identifies itself to the web server.

example:
<useragent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)</useragent>

httpauth

Specifies authorization headers to your request for HTTP Basic Authentication. HTTP provides a simple challenge-response authentication mechanism which may be used by a server to challenge a client request and by a client to provide authentication information. This configuration parameter takes a list of 5 colon delimited values that correspond to:
servername:portnumber:realm-name:username:password

example:
<httpauth>www.fakedomain.com:80:my_realm:foo:welcome</httpauth>

Note: You may include multiple <httpauth></httpauth> elements in your config files to support multiple sets of HTTP Authentication credentials.

baseurl

Creates the constant {BASEURL} which can be used in test cases (see 'Variables and Constants' section below).

example:
<baseurl>http://myserver</baseurl>

baseurl1

Creates the constant {BASEURL1} which can be used in test cases (see 'Variables and Constants' section below). This works in the same way as the 'baseurl' example above.

baseurl2

Creates the constant {BASEURL2} which can be used in test cases (see 'Variables and Constants' section below). This works in the same way as the 'baseurl' example above.

globalhttplog

Enables logging of HTTP requests/responses for all test cases. The HTTP requests sent and HTTP responses received are written to the http.log file. The available values you can set this to are:

  • yes - log HTTP for all test cases
    example:
    <globalhttplog>yes</globalhttplog>
  • onfail - log HTTP for test cases that fail only
    example:
    <globalhttplog>onfail</globalhttplog>

Note: If you also turn on logging for any individual test cases, it will produce duplicate log entries for the same request/response. Also, output logging is suppressed when running in a Plugin Mode (reporttype).

comment

Allows you to comment out parts of your config file. Anything contained within comment tags will not be processed. (I know it is braindead that we don't allow regular XML-style comments here.. sorry)

example:
<comment>this will be ignored</comment>

timeout

Sets a response delay timeout (in seconds) for every test case. If the response in any test case takes longer than this threshold, the HTTP request times out and the case is marked as failed. The default timeout if you do not specify one is 180 seconds.

example:
<timeout>10</timeout>


Note: This timeout setting may not always work when using SSL/HTTPS.

reporttype

This setting is used to enable output formatting that is compatible for use with specific external programs. The available values you can set this to are:

  • nagios - Output of WebInject in console mode will be compatible for use as a plugin for the Nagios monitoring program.
    Example:
    <reporttype>nagios</reporttype>
  • mrtg - Output of WebInject in console mode will be compatible for use as a plugin (external monitoring script) for the MRTG (Multi Router Traffic Grapher) program.
    Example:
    <reporttype>mrtg</reporttype>
  • external - Calls an external Perl module for post processing. You may write a Perl module that will be called after WebInject is finished running. Your module may access any of WebInject's global variables. This can be used to integrate with other external programs or to do any type of data processing at the end of your test run.
    Example:
    <reporttype>standard:Plugin.pm</reporttype>
    Sample Plugin.pm - this will send an email after WebInject runs:
    $message = "Passed: $casepassedcount,  Failed: $casefailedcount"; 
    exec(qq~ echo $message | mailx -s "WebInject Results" corey\@webinject.org ~);
  • standard - Standard formatted output mode (omitting this setting defaults to 'standard' mode).
    Example:
    <reporttype>standard</reporttype>

Note: Most output logging is suppressed when running in a Plugin Mode (reporttype).

globaltimeout

This setting is used when running in Nagios Plugin Mode (in combination with nagios reporttype). The value [given in seconds] will be compared to the global time elapsed to run all the tests. If the tests have all been successful, but have taken more time than the 'globaltimeout' value, a warning message is sent back to Nagios.

example:
<globaltimeout>10</globaltimeout>

gnuplot

Defines the path/location of the gnuplot executable on your system. This is only necessary to set if would like to have WebInject use gnuplot to create response time graphs and you have gnuplot installed somewhere on your system that is not on your PATH.

example:
<gnuplot>/usr/bin/gnuplot</gnuplot>

standaloneplot

Tells WebInject to create response time graphs when running in standalone/console mode (webinject.pl). Unless this is set to 'on', plotting/graphing is only available in GUI mode. A PNG image (plot.png) is generated in the current [webinject] directory.

example:
<standaloneplot>on</standaloneplot>

2.2 - Test Case Files (specifying in configuration file)

If you are using the GUI (webinjectgui.pl or webinjectgui.exe) to run your tests, you can not pass a test case filename from the command line (or use any other command line options). Instead, they are read out of config.xml. One of the configuration file settings in config.xml is used to name the test case files which you have created. You may specify any amount of test case files to process by placing each file name inside the proper (<testcasefile>) xml tags. If there is no configuration setting used to name your test case file(s), it will default to using a file named 'testcases.xml' in the current [webinject] directory. The files are processed in the order they appear in your config file.

A configuration file listing 3 test case files to process (tests_1.xml, tests_2.xml, tests_3.xml) may look something like:

<testcasefile>tests_1.xml</testcasefile>
<testcasefile>tests_2.xml</testcasefile>
<testcasefile>tests_3.xml</testcasefile>

Note: You can also use relative path names to point to test case files located in other directories or subdirectories.

2.3 - Command Line Options and Specifying Alternate Test Case/Config Files

You can run the WebInject Engine (webinject.pl) in standalone/console mode by calling it directly from the command line rather than from the [webinjectgui] GUI. When you do this, you can optionally pass it a test case file name and several command line options.

Usage:

webinject.pl [-c|--config config_file] [-o|--output output_location] 
             [-n|--no-output] [testcase_file [XPath]]

   or

webinject.pl --version|-v

Available Command Line Options

  • -c or --config : This option is followed by a config file name. This is used to specify an alternate configuration file besides the default (config.xml). To specify a config file in a different directory, you must use the relative path to it.
    Note: relative path from the webinject directory.

  • -o or --output : This option is followed by a directory name or a prefix to prepended to the output files. This is used to specify the location for writing output files (http.log, results.html, and results.xml). If a directory name is supplied (use either an absolute or relative path and make sure to add the trailing slash), all output files are written to this directory. If the trailing slash is ommitted, it is assumed to a prefix and this will be prepended to the output files. You may also use a combination of a directory and prefix.

    To clarify, here are some examples:

    To have all your output files written to the /foo directory:
    perl webinject.pl -o /foo/

    To have all your output files written to the foo subdirectory under your WebInject home directory:
    perl webinject.pl -o ./foo/

    To create a prefix for your output files (this will create output files named foohttp.log, fooresults.html, and fooresults.xml in the WebInject home directory):
    perl webinject.pl -o foo

    To use a combination of a directory and a prefix (this will create output files named foohttp.log, fooresults.html, and fooresults.xml in the /bar directory):
    perl webinject.pl -o /bar/foo

    Note: MS Windows style directory naming also works.
    Note: You must still have write access to the directory where WebInject resides, even when writing output elsewhere.

  • -n or --no-output : Suppresses all output to STDOUT except the results summary.

  • -v or --version : Displays the version number and other information.

Note: Command line options are only available when launching the WebInject Engine (webinject.pl) on its own, not from the GUI.

Passing a Test Case Filename

When you launch WebInject in console mode, you can optionally supply an argument for a testcase file to run. It will look for this file in the directory that webinject.pl resides in.

perl webinject.pl mytests.xml

If no filename is passed from the command line, it will look in config.xml for testcasefile declarations. If no files are specified, it will look for a default file named 'testcases.xml' in the current [webinject] directory. If none of these are found, the engine will stop and give you an error.

Note: If you pass a test case filename from the command line and also have testcasefile declarations in your config file, the files specified in the config file will not be processed (but all other config options are still used).

XPath/XNode

When you pass a test case filename to the WebInject Engine from the command line, you may also specify an extra argument that defines a single XPath/XNode. This will only execute the test case residing in the XPath/XNode you supply.

For example, to run only testcase 2 from your file named mytests.xml, you would call it like this:

perl webinject.pl mytests.xml testcases/case[2]

More Examples of Command Line Usage

Here are some examples to illustrate using webinject.pl from the command line:

1) Launching webinject.pl using the default config file and test case file:

perl webinject.pl

2) Launching webinject.pl specifying an alternate test case file and config file:

perl webinject.pl mytests.xml -c myconfig.xml

3) Launching webinject.pl from a different directory. As an example, you installed webinject in /usr/local/webinject. This will use defaults config.xml and testcase.xml files located in the same directory as webinject.pl:

perl /usr/local/webinject/webinject.pl

4) Launching webinject.pl from a different directory and specifying an alternate test case file and config file. As an example, you installed webinject in /usr/local/webinject. This will use myconfig.xml and mytests.xml files located in the same directory as webinject.pl:

perl /usr/local/webinject/webinject.pl mytests.pl -c myconfig.xml

4) Launching webinject.pl and specifying a relative path to an alternate testcase file and config file. As an example, you have your test case file and config file are located in a subdirectory named 'myfiles':

perl webinject.pl ./myfiles/mytests.pl -c ./myfiles/myconfig.xml

3 - Test Case Setup

3.1 - Summary

Test cases are written in XML files (using XML elements and attributes) and passed to the WebInject engine for execution against the application/service under test. This abstracts the internals of WebInject's implementation away from the non-technical tester, while using an open architecture [written in Perl] for those that require more customization or modifications.

There are several parameters (attributes) you can use in your cases, depending on what you are trying to accomplish. The only required parameters are the 'id' and the 'url'. If no verification parameters (verifypositive, verifynegative, verifyresponsecode, etc) are provided, the test case will be marked as "FAILED" if the HTTP request returns an HTTP Response Code that is not in the 100-399 range. See the "Pass/Fail Critera" section of this manual for more information.

3.2 - Minimal Example

A minimal test case may look something like:

<case
    id="1"
    url="http://myserver/test/test.html"
/>

3.3 - Available Parameters

id

Test case identifier used to identify the test case and set it's execution order.

description1

Text description for results report.

description2

Text description for results report.

method

HTTP request method, can be "get" or "post". This defaults to "get" if the parameter is omitted.

url

Full HTTP URL to request. You can use an IP Address or Host Name.

posttype

This parameter specifies the content type encoding used in submitting a form to the server ("Content-Type" field in the HTTP Header). This is only used in an HTTP POST (method="post"). The possible values are:
  • "application/x-www-form-urlencoded"
  • "multipart/form-data"
  • "text/xml"
  • "application/soap+xml"
Defaults to "application/x-www-form-urlencoded" if this parameter is omitted.

postbody

This is the data (body) of the request to be sent to the server. This is only used in an HTTP POST (method="post").

If you are sending "application/x-www-form-urlencoded" data, this parameter contains the string of text data you wish to send.

If you are sending "multipart/form-data" (used for form-based file upload as specified in RFC 1867), this parameter contains a string that represents the Perl code used to define the "Content" parameter of the Perl "POST" function. This string will be evaluated by the Perl interpreter using "eval". More details about the syntax can be found in the Perl documentation of the HTTP::Request::Common module. (sorry if this is a little cryptic, the example below should help).

If you are sending "text/xml" or "application/soap+xml" (used for web services), this parameter contains a link to an external file that contains the text (xml payload) that will be sent in the body of your request. This is done using the file=> syntax.
Example: postbody="file=>soap_payload.xml"

verifyresponsecode

HTTP response code for verification. Verification fails if the HTTP response code you specified does not match the HTTP response code you receive.

verifypositive

String in response for positive verification. Verification fails if this string does not exist in the HTTP response. This is matched as a Perl regular expression, so you can do some complex verification patterns if you are familar with using regex matching.

Note: Because your verification string is used as a regex, the following characters within it must be escaped with a backslash: {}[]()^$.|*+?\

verifypositive2

Additional positive verification. This works the same as 'verifypositive'.

verifypositive3

Additional positive verification. This works the same as 'verifypositive'.

verifypositive3

Additional positive verification. This works the same as 'verifypositive'.

verifynegative

String in response for negative verification. Verification fails if this string exists in the HTTP response. This is matched as a Perl regular expression, so you can do some complex verification patterns if you are familar with using regex matching.

Note: Because your verification string is used as a regex, the following characters within it must be escaped with a backslash: {}[]()^$.|*+?\

verifynegative1

Additional negative verification. This works the same as 'verifynegative'.

verifynegative2

Additional negative verification. This works the same as 'verifynegative'.

verifynegative3

Additional negative verification. This works the same as 'verifynegative'.

verifynextpositive

String in response for positive verification on next test case. Verification fails if this string does not exist in the HTTP response of the next test case that is executed.

verifynextnegative

String in response for negative verification on next test case. Verification fails if this string exists in the HTTP response of the next test case that is executed.

logrequest

Set to "yes" to log (in http.log) the HTTP request sent for the current test case. Logging disabled if this parameter is omitted or not equal to "yes".

logresponse

Set to "yes" to log (in http.log) the HTTP response received for the current test case. Logging disabled if this parameter is omitted or not equal to "yes".

parseresponse

Parse a string from the HTTP response for use in subsequent requests. This is mostly used for passing Session ID's, but can be applied to any case where you need to pass a dynamically generated value. It takes the arguments in the format "leftboundary|rightboundary", and an optional third argument "leftboundary|rightboundary|escape" when you want to force escaping of all non-alphanumeric characters. See the "Session Handling and State Management - Parsing Response Data & Embedded Session ID's" section of this manual for details and examples on how to use this parameter.

Note: You may need to prepend a backslash before certain reserved characters when parsing (sorry that is rather vague).

Note: Newlines (\n) are also valid boundaries and are useful when you need to use the end of the line as a boundary.

parseresponse1

Additional parameter for response parsing.

parseresponse2

Additional parameter for response parsing.

parseresponse3

Additional parameter for response parsing.

parseresponse4

Additional parameter for response parsing.

parseresponse5

Additional parameter for response parsing.

sleep

Number of seconds to sleep after the test case. This used to add spacing between cases in order to throttle the rate it sends requests.

Note: The WebInject GUI runs in a single process/thread. Therefore, the GUI will not be responsive during the time it is "sleeping".

errormessage

If a test case fails, this custom 'errormessage' will be appended to the 'TEST CASE FAILED' line (on STDOUT and the HTML Report). This may be useful to give a bit more information on what a failed test means, like "couldn't connect to the application" or "couldn't access the login page".

addheader

This is used to add an addition header to an outgoing HTTP request.

Example: addheader="SOAPAction: urn:example-org:demos#Method"

You may add multiple headers, separating each with a pipe character.

Example: addheader="Foo: bar|Boo: far"

3.4 - Full Examples

Sample test cases using multiple parameters:

<case
    id="1"
    description1="short description"
    description2="long description"
    method="post"
    url="http://myserver/test/login.jsp"
    postbody="username=corey&password=welcome"
    verifypositive="verify this string exists"
    verifynegative="verify this string does not exist"
    logrequest="yes"
    logresponse="yes"
    sleep="3"
/>

<case
    id="2"
    description1="short description"
    description2="long description"
    method="get"
    url="http://myserver/test/send.jsp?value={TIMESTAMP}"
    verifypositive="verify this string exists"
    verifynextpositive="{TIMESTAMP}"
/>

Here is a sample test case showing a "multipart/form-data" encoded form-based file upload:

<case 
    id="1" 
    description1="sample test case - POST" 
    description2="verify file upload" 
    method="post" 
    url="http://cgi-lib.berkeley.edu/ex/fup.cgi" 
    postbody="( upfile => ['config.xml'], note => 'MYCOMMENT' )" 
    posttype="multipart/form-data" 
    logrequest="yes" 
    logresponse="yes" 
    verifypositive="MYCOMMENT" 
/>

3.5 - Numbering Test Cases and Execution Order

Test Cases are numbered using the "id=" parameter. They will be sorted and executed in sequential order based on these numbers, not the physical position of the Test Case within your file. You are allowed to leave gaps in the numbering and have them in any order in the file.

3.6 - Parent XML Tags and Attributes (repeating test case files)

Make sure your entire set of test cases is wrapped with the proper parent tags:

Your file should begin with:

<testcases>

and end with:

</testcases>

There is also a "repeat" attribute you can set within the parent tag to specify the number of times you would like a file of test cases to run.

For example, to have a test case file run 5 times, your file should open with:

<testcases repeat="5">

3.7 - Valid XML and Using Reserved XML Characters

You may only use valid XML in your test cases. Malformed XML or mixed content will not be accepted by the parser that is used to read the test cases.

However, you may find it necessary to use such characters within an XML Attribute to define your test case. Most of these situations are handled programmatically behind the scenes for you as a user. For example, the "&" character would normally not be acceptable to an XML parser since it is a reserved character. Since this character is used in URL query strings (which are necessary in many/most test cases), it is handled as a special case and you may use them within your test case XML.

There are two special cases to be aware of:

less than (<) character:

Anywhere you use this character in your test cases (except of course, enclosing your actual XML tags), you must escape it with a backslash (failure to do so will make the test case parser croak).

For example, the following testcase parameter will not work like this:

verifypositive="<OPTION SELECTED>APPLE"

Instead, it should be written like:

verifypositive="\<OPTION SELECTED>APPLE"

quotes (single or double):

If you need to use quotes anywhere within a test case parameter, you need to make sure that the quotes are nested properly. The quotes (single or double) used to encapsulate your attribute must be different from the quotes you use within your attribute (both single and double quotes are valid to encapsulate an XML attribute).

For example:

verifypositive=" "this" "

will not work

verifypositive=' 'this' '

will not work

verifypositive=" 'this' "

is valid

verifypositive=' "this" '

is valid

3.8 - Variables and Constants

Certain constants and variables can be passed from your test cases to the WebInject engine. They may be used in a test case as a keyword contained within curly braces, and are evaluated/substituted at runtime.

  • {TIMESTAMP} : Substituted with the current timestamp (floating seconds since the epoch, accurate to microseconds)
  • {PARSEDRESULT} : Substituted with the result of the response parsing from a 'parseresponse' test case parameter
  • {PARSEDRESULT1} : Substituted with the result of the response parsing from a 'parseresponse1' test case parameter
  • {PARSEDRESULT2} : Substituted with the result of the response parsing from a 'parseresponse2' test case parameter
  • {PARSEDRESULT3} : Substituted with the result of the response parsing from a 'parseresponse3' test case parameter
  • {PARSEDRESULT4} : Substituted with the result of the response parsing from a 'parseresponse4' test case parameter
  • {PARSEDRESULT5} : Substituted with the result of the response parsing from a 'parseresponse5' test case parameter

(See the "Parsing Response Data & Embedded Session ID's" section for details and examples on how to use these {PARSEDRESULT} variables)

  • {BASEURL} : Substituted with the value for 'baseurl' specified in your config file
  • {BASEURL1} : Substituted with the value for 'baseurl1' specified in your config file
  • {BASEURL2} : Substituted with the value for 'baseurl2' specified in your config file

{BASEURL} Example:

If you a have a test case that uses the parameter:

url="http://myserver/test/login.jsp"

You could create this line in your config.xml file:

<baseurl>http://myserver</baseurl>

You can then rewrite the test case parameter as:

url="{BASEURL}/test/login.jsp"

This is helpful if you want to point your tests at different environments by changing a single setting.

Setting Variables/Constants Within Test Case Files:

You may also set constants in your test case file that you can reference from your test cases. This makes it convenient to change data in a single place that is easy to reference from multiple test cases.

The following example of a test case file shows how you can use them:

<testcases repeat="1">

    <testvar varname="LOGIN_URL">http://myserver/login.php</testvar>
    <testvar varname="LOGIN1">bob</testvar>
    <testvar varname="PASSWD1">sponge</testvar>
    <testvar varname="SUCCESSFULL_TEST_TEXT">Welcome Bob</testvar>
     
    <case
        id="1"
        description1="login test case"
        description2="verify string login"
        method="post"
        url="${LOGIN_URL}"
        postbody="login=${LOGIN1}&passwd=${PASSWD1}"
        verifypositive="${SUCCESSFULL_TEST_TEXT}"
    />

</testcases>

4 - Pass/Fail Criteria

4.1 - Verifications

In each test case, you can set Verifications that will pass or fail depending on the existence of a specified text string (or regex) in the content of the HTTP response you receive.

'verifypositive' - This Verification fails if the string you specified does not exist in the HTTP response you receive.
'verifynegative' - This Verification fails if the string you specified exists in the HTTP response you receive.

'verifypositive1', 'verifypositive2', 'verifypositive3', 'verifynegative1', 'verifynegative2', 'verifynegative3' work the same way.

'verifynextpositive' and 'verifynextnegative' work the same way, but the verification takes place on the next test case rather than the current one.

4.2 - HTTP Response Code Verification

In each test case, you can set a Verifications that will pass or fail depending on the HTTP response code.

'verifyresponsecode' - This Verification fails if the HTTP response code you specified does not match the HTTP response code you receive.

If you do not specify this test case parameter, the HTTP Response Code Verification is marked as "Failed" if the HTTP request returns an HTTP response code that is not in the success range (100-399). It is marked as "Passed" if the HTTP Response Code is in the success range (100-399).

4.3 - Test Case Pass/Fail Status

If any of the Verifications defined within a test case fail, or if the HTTP Response Code Verification fails, the test case is marked as "FAILED". If all of the Verifications defined within a test case pass, and the HTTP Response Code Verification passes, the test case is marked as "PASSED". These items are updated in real-time during execution.

5 - Output/Results/Reporting

5.1 - Results Display in the User Interface (Status, Monitor, RT Graph)

Results of the test execution are displayed in tabbed windows on the User Interface if you are running the WebInject GUI. Not all of the status details displayed in 'results.html' are shown in the Status window on the UI. Response times, runtime statistics, and a response time graph (when gnuplot is configured) are displayed in the Monitor window on the UI.

5.2 - Results File in HTML format (results.html)

An HTML file (results.html) is generated to display detailed results of the test execution. It is written into the directory that WebInject runs from and is overwritten each time the tool runs. The file contains data passed from the test case file (test case identifiers/descriptions, etc) as well as information generated from the test engine (test case pass/fail status, execution times, etc). This is where the most detailed results data can be found.

Note: Most output logging is suppressed when running in a Plugin Mode (reporttype).

5.3 - Results File in XML format (results.xml)

An XML file (results.xml) is generated to display results of the test execution. It is written into the directory that WebInject runs from and is overwritten each time the tool runs. The file contains data passed from the test case file (test case identifiers/descriptions, etc) as well as information generated from the test engine (test case pass/fail status, execution times, etc).

Note: Most output logging is suppressed when running in a Plugin Mode (reporttype).

5.4 - Results in STDOUT

If you are running the WebInject Engine (webinject.pl) as a standalone test runner (text/console application), results are sent [in plain text format] to the STDOUT channel as the tests execute. The same level of detail that is written to results.html is also written here.

Note: The results sent to STDOUT will be different if when running in a Plugin Mode (reporttype).

5.5 - HTTP Log File (http.log)

A log file (http.log) is generated to capture HTTP requests that are sent to the web server of the system under test and HTTP responses that are received from the system under test. Whether or not HTTP logging is turned on depends on a setting in the configuration file and if you have logging parameters turned on in each test case. See the "Configuration - Configuration File (config.xml)" and "Test Case Setup - Available Parameters" sections of this manual for more information on logging to the http.log file.

Note: Most output logging is suppressed when running in a Plugin Mode (reporttype).
Note: "Content-Length" and "Host" HTTP headers are automatically added to outgoing HTTP POST requests, but are not shown in http.log.

6 - Session Handling and State Management

6.1 - Summary

HTTP is a stateless protocol, meaning each request is discrete and unrelated to those that precede or follow. Because of the stateless nature of the protocol itself, web applications or services use various other methods to maintain state. This allows client connections to be tracked and connection-specific data to be maintained. If your server requires the client to maintain state during a session, then your test tool must be able to handle this as well.

6.2 - Cookies

One way to maintain session state is with HTTP Cookies. WebInject automatically handles Cookies for you (like a browser would). When a "Set-Cookie" is sent back in the HTTP header from the web server, the Cookie is automatically stored and sent back with subsequent requests to the domain it was set from.

6.3 - Parsing Response Data & Embedded Session ID's (Cookieless)

Embedded Session ID's ("Cookieless" session management) is another approach to maintaining state. Session ID's are written to the content of the HTTP response that is sent to the client. When the client makes a subsequent HTTP request, the Session ID string must be sent back to the server so it can identify the request and match it with a unique session variable it is storing internally. The client sends the string embedded in the URL or embedded in the post body data of each HTTP request.

In order to do this, WebInject provides a method of parsing data from an HTTP response to be resent in subsequent requests. This is done using the 'parseresponse' parameter and the '{PARSEDRESULT}' variable in your test cases.

There are also 5 additional parsing parameters/variables available if you need to parse multiple values from a single response. They work the same as these and are named:
parseresponse1/{PARSEDRESULT1}
parseresponse2/{PARSEDRESULT2}
parseresponse3/{PARSEDRESULT3}
parseresponse4/{PARSEDRESULT4}
parseresponse5/{PARSEDRESULT5}

Note: This parsing mechanism may be used for any situation where you need to resend data to the server that was sent to you in a previous response. There are other circumstances besides maintaining session where this may be useful.

Example of maintaining the ViewState with ASP.NET:

ASP.NET may use a "__VIEWSTATE" variable to maintain state between requests. When you request a page that uses this, you will see it as a hidden form field within the HTML source:

<html>
...
<form method="post" action="default.aspx">
<input type="hidden" name="__VIEWSTATE" value="dDwtMTA4NzczMzUxMjs7Ps1HmLfiYGewI+2JaAxhcpiCtj52" />
...
</html>

To maintain state, you need to grab this value so you can resend it in subsequent requests. To do this, you would add the following parameter to your test case:

parseresponse='__VIEWSTATE" value="|"|escape'

This will grab whatever is between the left boundary (__VIEWSTATE" value=") and the right boundary (") and assign to the system variable named {PARSEDRESULT}. Since the 'escape' argument was used, it will also escape all of the non-alphanumeric characters with their url hex values (.NET requires this). (Notice I switched to using single quotes for the parameter value so it wouldn't get confused with the double quotes I was using in my boundaries.)

Whenever you use the {PARSEDRESULT} variable in a subsequent test case, it will be substituted with the last value you parsed:

postbody="value=123&__VIEWSTATE={PARSEDRESULT}"

Will be sent to the server as:

value=123&__VIEWSTATE=dDwtNTA4NzczMzUxMjs6Ps1HmLfiYGewI%2b2JaAxhcpiCtj52

Example of parsing the Session ID from an HTTP response header and sending it as part of the URL:

You may receive a Session ID in a HTTP response header that needs to be parsed and resent to the server as part of a URL rather than in a cookie.

To parse the Session ID from a header that contains:

Set-Cookie: JSESSIONID=16CD67F723A6D2218CE73AEAEA899FD9; Path=/

You would add the following parameter to your test case:

parseresponse="JSESSIONID=|;"

This will grab whatever is between the left boundary (JSESSIONID=) and the right boundary (;) and assign to the system variable named {PARSEDRESULT}.

Now whenever you use the {PARSEDRESULT} variable in a subsequent test case, it will be substituted with the last value you parsed:

url="http://myserver/search.jsp?value=123&;JSESSIONID={PARSEDRESULT}"

Will be sent to the server as:

http://myserver/search.jsp?value=123&;JSESSIONID=16CD67F723A6D2218CE73AEAEA899FD9

7 - User Interface (GUI)

7.1 - General

Summary

The User Interface (webinjectgui.pl or webinject.exe) is a small [Perl/Tk] GUI wrapper used to run the WebInject Engine (webinject.pl).

Status Bar

The status bar shows visual progress of the current iteration of the test case file being processed. If you are using the "repeat" attribute to run multiple iterations of a test case file, the status bar will reset as each iteration starts. If you have multiple test case files configured to run, the status bar will reset as each new test case file is loaded for execution.

Engine Status Window

This window shows the status of the WebInject engine as it runs. It displays when execution begins, the current test case file it is processing, and when execution finishes.

Status Light

The status light is the small box next to the status bar. While your tests are running, the light will turn amber. After your tests complete, the status light will turn either red or green. If all test cases passed, the light turns green. If any verifications failed, it turns red.

Disable Monitor

This checkbox is used to completely disable the Monitor Window and all of it's underlying real-time monitoring functionality (including graph generation). This can not be selected during a test run. It must be enabled or disabled before execution begins.

7.2 - Status Window

Minimal Output

Selecting this option before you run your test cases will suppress details of each test case from being displayed in the output window. The only information displayed for each case is "PASSED" or "FAILED".

Response Timer Output

Selecting this option before you run your test cases will display the server response time for each case as it runs.

7.3 - Monitor Window

Response Time Graph

This graph displays response times in seconds for TTLB (time to last byte) of HTTP requests sent during execution. The timer contains the round trip time for the request/response. As responses are received, a new graph is generated and displayed to the Monitor Window in real-time, replacing the previous one.

The x-axis represents response time in seconds

The y-axis represents the time of day. Initially the values shown correspond to the minutes after the hour, but then adjust to the appropriate setting as time elapses.

The scale of the axes adjusts automatically to fit the data being displayed.

Response Times

This shows response times in seconds for TTLB (time to last byte) of HTTP requests sent during execution. The timer contains the round trip time for the request/response. Values for Min, Max, and Avg responses are displayed.

Runtime Counts

This shows counter values for the current execution. Values for the total number of test cases run (total), passed, and failed are displayed.

Line Graph

Selecting this changes the graph style to a line graph. It is effective as of the next time the graph image is updated. This is the default graph style.

Impulse Graph

Selecting this changes the graph style to an impulse graph. It is effective as of the next time the graph image is updated.

No Graph

Selecting this turns off generation and display of the graph. Normally, as responses are received a new graph is generated and displayed to the Monitor Window in real-time, replacing the previous one. This can take time and resources (CPU), especially when there is a large data set to be plotted. Resource usage will be most apparent when response times are quick, as the graph will need to be re-generated at a faster rate. If you do not want any time and resources spent creating the graphs, you may select this "No Graph" option. It can be changed during execution to turn on and off graphing as necessary. Response time data is still collected while this option is selected.

Clear Graph

Clicking this button clears (resets) the graph. It is effective as of the next time the graph image is updated.