 |
 |
JTransit RedLine
RedLine is used to perform automated testing of any web application or JDBC database. It can be used to record and play back complete user sessions, saving them to script files that can be annotated by hand with checks, loops, load points, etc.
There is also a command-line component that you can use to perform automated tests and load tests of your application, with or without a web server. The command-line interface is most useful as part of an automated build process or script.
At the end of this document is a FAQ with common questions about RedLine usage.
GUI Usage
We hope to document the RedLine GUI soon. For now, please use the command-line interface. Thank you for your patience.
Command-Line Usage
java -cp (classpath) jtransit.loadtest.LoadTester (script) (args) > (dump file)
Where (classpath) contains at least
- application-specific jar file or classes dir (eg, gen/classes)
- jtransit-redline.jar
- JDBC driver .jar file (if running direct-to-database tests)
- app server .jar file (eg, orion.jar)
- all other 3rd-party .jar files (xerces.jar, Acme.jar, js.jar, log4j.jar, etc.)
and (script) is the path/name of the script file to run (eg, loadtest.script), (args) are any arguments required by the script or referenced scripts, and (dump file) is an optional file to write the output to.
Config file format is one command per line. Commands can be one of the
following:
- # [(comment)...] - blank lines are also ignored
- CONF [(jtransit.xml file)] - configure JTransit runtime
- ERROR [(message)...] - show error and quit
- GET
(url) (varname) - download url and store in var (varname should be quoted)
- HASH (string) (varname) - hash string and store in var (varname
should be quoted)
- IFEQUAL (value1) (value2) - do next command if values are equal
- IFNOTEQUAL (value1) (value2) - skip next command if values are equal
- LOOP [(#times)] - repeat entire script (once | times)
- POOLSQL (dsname) (sql) - run sql using pooled connection
- RAND (min) (max) (varname) - set random int (varname should be quoted)
- READ (file) (varname) - read file and store in var (varname should
be quoted)
- REPORT
(script) (min#threads) (max#threads) (watchStr) - generate a performance
report by running script using a range of threads from min to max (inclusive),
looking for watchStr in the output
- RUN
(uri) (varname) - run uri and store in var (varname should be quoted)
- SET (varname) (value)... - set variable by concatenating remaining
args (varname should be quoted)
- SLEEP (millis) - wait a bit
- SPIDER
(html) (save dir) [(flags)] - spider a chunk of HTML code and save results
(images and/or referenced HTML pages) in a directory
- SQL
(driver) (url) (user) (pass) (sql) - run sql
- THREAD (script) [(#threads)] - run script in separate thread(s)
- WRITE (string) (file) - create or overwrite file
Arguments to commands can be strings (double-quoted Java-style), or variables
(unquoted runs of non-whitespace), or command-line args ($1, $2, etc.). The
special value $t can be used to represent the thread number.
GET and RUN
GET does an HTTP GET to any web server, and stores the results in a variable.
The following example retrieves the page at
http://127.0.0.1/jtdc.taf
and stores the HTML source in the p1 variable.
GET "http://127.0.0.1/jtdc.taf" "p1"
RUN will connect internally (by starting up a private instance of the
JTransit core) instead of hitting the web server, so you need to add everything
to the classpath of the load tester that you normally need when running
the server. The syntax for the RUN command is the same as for GET except
you only include a URI (the stuff after the server name). So your RUN command
should look like this:
RUN "/jtdc.taf" "p1"
RUN and GET store their results in a variable, so if you want to write
them to a file you need to use the WRITE command like this:
RUN "/jtdc.taf" "p1"
WRITE p1 "p1.html"
Note that in the WRITE command, the p1 variable is not quoted. This is
because you want to write the contents of the variable, not the literal
text "p1", to the "p1.html" file.
The GET command sets another variable called $responseCode with the HTTP
server's response code sent before the headers of the request. A normal
response code is 200, and you can check for that using the following code:
GET "http://www.yahoo.com/robots.txt" "robotFile"
WRITE robotFile "yahoo-robots.txt"
IFNOTEQUAL $responseCode "200"
ERROR "error " $responseCode ": check yahoo-robots.txt for
details"
REPORT
REPORT allows you to generate statistics for specific page hits in your
application, within a range of concurrent requests. In order to use REPORT,
you must create at least two scripts, one with the REPORT command and one
with at least one GET or RUN command. For example, to test a GET of http://127.0.0.1/test.taf,
you could use the following command (which contains an embedded single-command
GET script, and should be all on one line):
REPORT "GET \"http://127.0.0.1/test.taf\" \"p1\""
"1" "4" "GET: downloaded URL: http://127.0.0.1/test.taf"
Another way to accomplish the same thing is to have two script files,
one with the following READ and REPORT commands:
# main script
READ "get.script" "script"
REPORT script "1" "4" "GET: downloaded URL: http://127.0.0.1/test.taf"
and a second file called get.script with the following command:
# script to test the app one time through
GET "http://127.0.0.1/test.taf" "p1"
The two-file method is easier to maintain, and multiple commands and comments
can be added to the get.script to more fully test the entire application.
An example of the output of the preceding REPORT command follows.
Load Test Report for "GET: downloaded URL: http://127.0.0.1/test.taf" Event
Threads Min Max Avg
------- ------- ------- -------
1 3303 3303 3303
2 4413 4611 4512
3 2222 5907 4628
4 5445 19309 15635
Each row of the report shows the statistics when the script is run with a certain number of threads. The Min, Max, and Avg columns show the minimum, maximum, and average time for the task to run (in milliseconds). Note that only the GET and RUN commands will produce statistics for use by the REPORT command.
SPIDER
SPIDER allows you to parse blocks of HTML code and download all the referenced images and/or pages in that code, saving the downloaded files in a directory or directory structure. This can be used to save a web site for offline browsing, or to more closely mimic the load placed on a server by typical web browsers.
Various flags allow you to spider a site in different ways depending on what you want to accomplish. The flags and defaults are shown in the table below. To negate a flag, prefix with the letter "n". Flags should be included in a single string given as the third argument to the SPIDER command separated by commas, ie, "ni,d" would turn off image downloading and enable document downloading.
| Flag |
Default
|
Description
|
| i |
on |
download referenced images
|
| d |
off |
download referenced documents (HTML
pages and download links) |
| ri |
off |
re-download images that have been downloaded
already (either by this spider or by others using the same download directory)
|
| rd |
off |
re-download documents that have been
downloaded already |
| w |
off |
wait random 1-10 seconds between each
document |
For example, the following script would save the google.com home page and all images on it in the "pages" directory under the current directory:
GET "http://www.google.com/" "p1"
WRITE p1 "pages/index.html"
SPIDER p1 "pages"
The following script would save the entire web site http://www.dogparksoftware.com:
GET "http://www.dogparksoftware.com/" "p1"
WRITE p1 "pages/index.html"
SPIDER p1 "pages" "d"
SQL
The SQL command provides a way to either load test the database directly, or to test SQL commands as part of a QA test suite (ie, if you have stored procedures that get changed during development and want to develop test suites for those). The timings reported include connecting to the database and closing that connection.
Pass the same driver you have in your jtransit.xml config file. For example, if your database is Oracle, use jdbc.oracle.driver.OracleDriver.
FAQ
The following questions are frequently asked.
Q: Can I do a REPORT on the SQL command, and if so,
what should my watch string be?
A: Yes, you can. For any command, you can always do a script that uses that command (without a REPORT) and see what the output is, and then use those output summary names as your watch string. In the case of the REPORT command, the following watch strings are available:
SQL: loaded JDBC driver
SQL: opened [num connections] connection(s)
SQL: executed [sql command here]
SQL: closed [num connections] connection(s)
I would report on both the "SQL: opened # connection(s)" string and then the "executed *" string(s). The other two are uninteresting since they happen outside the context of your application (if you're using pooling).
Q: If my script has GET's for different URL's, can I REPORT on all of those URL's, or can I only report on one of them?
A: You can use as many REPORT commands as you want,
however for one REPORT command you can only report on a single URL at a time.
So the only reason for having multiple URL's in the same script is if you
have to perform some preliminary task like logging in before hitting the
URL you want to time.
For example, the following two scripts could be used to time two separate
URL's:
Script 1 (main.script):
READ "sub.script" "theScript"
SET "url" "http://www.yahoo.com/"
SET "watch" "GET: downloaded URL: " url
REPORT theScript "1" "4" watch
SET "url" "http://www.google.com/"
SET "watch" "GET: downloaded URL: " url
REPORT theScript "1" "4" watch
Script 2 (sub.script):
GET url "p1"
IFNOTEQUAL $responseCode 200
ERROR "error fetching " url ": " $responseCode " response"
Running the main.script generates a report for yahoo.com and google.com's
home pages.
Q: How are command-line arguments typed in? My command is java -cp %CLASSPATH% jtransit.loadtest.LoadTester main.script (args) > report.txt
A: The arguments are simply passed as strings in the order specified. So if the above command were typed as "java -cp %CLASSPATH% jtransit.loadtest.LoadTester main.script config.xml 7 a=6 > report.txt", then $1 is the same as "config.xml" in your scripts, and $3 is the same as "a=6" in scripts.
Q: How do I access the arguments typed in from the command line?
A: You use $1, $2, ... instead of quoted string arguments. For example:
# load configuration file named in first command-line arg
CONF $1
Q: Is there a way to run a script in the main script without using the thread or report command?
A: No, but if you want to just run commands in a separate script file one time in a single thread, just use "1" as the threads argument to the THREAD command. The main thread will wait until the commands in the THREAD script complete before continuing.
|
|
 |
