The Web Transactions configuration wizard in Nagios XI uses WebInject to handle transaction logic. Please reference the WebInject instructions below when setting up the Web Transactions wizard.
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.
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>http://127.0.0.1:8080</proxy>
<proxy>http://username:password@127.0.0.1:8080</proxy>
<useragent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)</useragent>
<httpauth>www.fakedomain.com:80:my_realm:foo:welcome</httpauth>
<baseurl>http://myserver</baseurl>
<globalhttplog>yes</globalhttplog>
<globalhttplog>onfail</globalhttplog>
<comment>this will be ignored</comment>
<timeout>10</timeout>
<reporttype>nagios</reporttype>
<reporttype>mrtg</reporttype>
<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 ~);
<reporttype>standard</reporttype>
<globaltimeout>10</globaltimeout>
<gnuplot>/usr/bin/gnuplot</gnuplot>
<standaloneplot>on</standaloneplot>
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.
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
perl webinject.pl -o /foo/
perl webinject.pl -o ./foo/
perl webinject.pl -o foo
perl webinject.pl -o /bar/foo
Note: Command line options are only available when launching the WebInject Engine (webinject.pl) on its own, not from the GUI.
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).
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]
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
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.
A minimal test case may look something like:
<case
id="1"
url="http://myserver/test/test.html"
/>
file=>
syntax.postbody="file=>soap_payload.xml"
{}[]()^$.|*+?\
{}[]()^$.|*+?\
addheader="SOAPAction: urn:example-org:demos#Method"
addheader="Foo: bar|Boo: far"
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"
/>
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.
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">
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:
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"
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
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.
(See the "Parsing Response Data & Embedded Session ID's" section for details and examples on how to use these {PARSEDRESULT} variables)
{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.
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>
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.
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).
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.
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.
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).
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).
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).
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.
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.
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.
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.
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
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
The User Interface (webinjectgui.pl or webinject.exe) is a small [Perl/Tk] GUI wrapper used to run the WebInject Engine (webinject.pl).
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.
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.
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.
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.
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".
Selecting this option before you run your test cases will display the server response time for each case as it runs.
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.
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.
This shows counter values for the current execution. Values for the total number of test cases run (total), passed, and failed are displayed.
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.
Selecting this changes the graph style to an impulse graph. It is effective as of the next time the graph image is updated.
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.
Clicking this button clears (resets) the graph. It is effective as of the next time the graph image is updated.
Article ID: 897
Created On: Tue, Mar 16, 2021 at 11:43 AM
Last Updated On: Tue, Mar 16, 2021 at 4:48 PM
Authored by: rspielman
Online URL: https://support.nagios.com/kb/article/webinject-instructions-897.html