AWBot 1.1 Documentation


Install, Setup and Use AWBot

AWBot common use is made in 4 steps:


To use AWBot, you must have the following :
- A computer with a command line access (DOS, Korn Shell, ...)
- A perl interpreter working on this computer with the following Perl add-on modules :
* Time:HiRes
and if you need to make SQL requests to prepare your test:
* DBD::YourSGBD (DBD::mysql, DBD::Oracle, DBD::Sybase, DBD::ODBC...)

You can find all those free modules on the net. Remember AWBot is not a web indexing robot but a client tool to emulate visitors to your site. This free tool is great for testing the stability of your web site, be it a casino, blog, video, or most any type of site. Don't forget to consult our FAQ page if you are having trouble setting up.

Create a testconfig file

After downloading and uncompressing AWBot distribution in a directory, you will find the following files :
./docs/*HTML documentation files (Open index.html to get the table of contents)
./bin/awbot.plThis is AWBot main script
./bin/awbotlaunch.plA launcher to launch several sessions of the bot
./bin/awbot.test.confA sample of config file for using AWBot
./bin/lang/*Language files

The next step is to create a test/config file:

1- Copy awbot.test.conf into awbot.mytestconfig.conf.

2- Edit the "INIT PARAMETERS" section of this config file with your own test setup:
* Change OUTPUTDIR parameter to the value of the directory that will contains all tests results (AWBot output files) and create this directory (must have write permissions).
* Change SERVER parameter with value of your domain name. For example ""
* If your site need a HTTP Basic authentication, use USER and PASSWORD to setup name and password of users used by the bot when authentication is required. You will be able to overwrite those parameters when you will launch several sessions of the bot using a user/password file list (See later).
* Change DELAY parameter to set the time the bot will wait between sending each URL.
3- Edit the "LIST OF ORDERED URLS TO TEST" section of this config file with your own test setup:
* You must add here the list of all URLs you want the bot to test. All URLs between "" and "" keywords will be sent in chronological order by the bot to the server. If your URL is a page you access from a link you must declare this url with the GET keyword, if your URL need to be requested from a HTML form, you must declare the link using the POST keywords (Fields are sent wth same URL syntax than GET requests). This is an example of this 2 URLs to test: <ACTIONS>
GET "http://$SERVER/"
POST "http://$SERVER/cgi-bin/myformact?field1=xxx&field2=bbb
Note that you can use in your testconfig file value of a parameter declared before using the "$" prefix to tell the bot to replace parameter with value ($SERVER will be replaced by ""

4- If you need to catch a parameter in the response of an URL, you can use the VAR keyword and the POSIX regex syntax (like 'sed', 'awk' and a lot of Unix tools) to extract the value.
For example if you have in your testconfig file the following actions list:
GET "http://$SERVER/"
VAR "AUTHORNAME:Welcome on this page made by (\w+)"
GET "http://$SERVER/cgi-bin/$AUTHORNALE"
This means that the bot will first sent the request of the home page for $SERVER, wait the result, will search the string "Welcome on the Web Site xxx" and will store the value of xxx in the $AUTHORNAME variable. Then this variable $AUTHORNAME is used later for next url.

5- In this same section you can also use the CHECKYES or CHECKNO keywords to ask the bot to check a particular keyword or not in the page returned by the request.
This is a simple example to start:
GET "http://$SERVER/"
CHECKYES "Welcome on this page"
CHECKNO "access forbidden"

6- See Directives of testconfig file page for an explanation of all other available keywords.

7- If you used SEQUENCE or SQL keywords, you must enable the Perl module for your SGBD. For this edit the file and uncomment the corresponding line after the "#__START_OF_SGBD_SETUP" line.

Setup is finished. You can jump to the Run AWBot section.

Run AWBot

1- You can first launch AWBot as a standalone process from the command line, like this : -config=awbot.mytestconfig.conf [otheroptions]

otheroptions can be :
-server=xxx Overwrite SERVER value of testconfig file
-user=xxx Overwrite USER value of testconfig file
-password=xxx Overwrite PASSWORD value of testconfig file
-delay=n Overwrite DELAY value of testconfig file
-timeout=n Overwrite TIMEOUT value of testconfig file
-nostopiferror AWBot continues with next test when an error occurs
-verbose Output file is also reported on screen
-debug=X To add debug informations lesser than level X

Results are stored in the output file myconfigtest.conf.out in the directory defined by the OUTPUTDIR in the config file.

This is an example of outputfile you can get from a simple input file
Input file
Result/Output file

2- You can use the bot launcher if you need several processes (for load benchmarks): -config=awbot.myconfigtest.conf -nbsessions=n

With the awbotlauncher, you will get one output file for each sessions ran. Each output file will contains the process ID of the session in its name. Example for -nbsessions=3, you will get 3 files:

Note 1: Don't forget that if you want to have results for n simultaneous sessions, you should set DELAY parameter to 0.
Note 2: Don't forget to purge the output directory before running a multi-session test if you want to obtain a directory with all files of last test.

If you add the parameter -authentication=@userpasswordfile when you launch awbotlaunch, each session of the bot will be launched with a different value of USER and PASSWORD whatever are their value in config file. Values for USER/PASSWORD will be thoose found in file userpasswordfile. Format for this file is:
user1 password1
user2 password2
usern passwordn

Analyze Results

Just open the output file. You will, for each request, time spent or the error message if URL failed.

As you can see in the preceding example, the output file contains several parts:
The first part is summary of INIT parameters
TEST awbot 1.0 (build 1.3)
Config file: awbot.mytest.conf
Server: - User: test - Delay: 0
Botname: AWBot - TimeOut: 120 - MaxSize: 0
Date: 2002-07-03 23:12:51
Process ID: 2328

The part "PRE ACTIONS" and "POST ACTIONS" are results of all PRE and POST ACTIONS commands

The part "ACTIONS" is the list of all URLs in your "<ACTIONS>" section. You can see time when request was submitted with following format:
YYY/MM/DD-HH:MM:SS:ms (ms are milliseconds)
You have a line under each URL to test with time spent by server to send page. If a CHECKYES or CHECKNO check rule mad on response fails, you will also get an error message.

The last part is a summary of response time, and checks for global test and each URLs.
Total requests to do: 2
Total requests sent: 2 (2 answered)
Total requests duration: 6827 ms
Average requests response time: 3413 ms/request
Total Check Yes: 1/1 No: 0/0
Faster request response time: URL 2 - 2000 ms
Slower request response time: URL 1 - 4827 ms
URL 1 - Duration: 4827 ms - Cumul: 4827 ms - Check Yes: 1 / 1 No: 0 / 0
URL 2 - Duration: 2000 ms - Cumul: 6827 ms - Check Yes: 0 / 0 No: 0 / 0