AWBot 1.1 Documentation

AWBot configuration directives/options for config/test file

AWbot need a config/test file to know what site and kind of action it should test. This page presents all available directives/options you can use to build your config file.
Note that one config/test file is provided with AWBot (awbot.test.conf).

First this is content of this sample file :
All lines starting with "#" are comments. All other lines must start with one of the allowed keyword directives/options explained in this page.

# AWBot 1.0 Config file #----------------------------------------------------------------------------- # Note that everywhere in the file you can include : # __MONENV__ to ask AWBot to replace tag by value of environment variable MONENV # $MYVAR to ask AWBot to replace tag by value of variable already defined # in this same config file. # $STARTSESSION is defined to 1 if AWbot is ran as a standalone process, # to first session number if ran from AWBotlaunch. # $NUMSESSION is defined to 1 if AWbot is ran as a standalone process, # to session number if ran from AWBotlaunch. # $NBSESSION is defined to 1 if AWbot is ran as a standalone process, # to total number of sessions ran from AWBotlaunch. # You can also include perl code in values everywhere in the file. #----------------------------------------------------------------------------- # INIT PARAMETERS SECTION #----------------------------------------------------------------------------- # Put here all global parameters of your test configuration. # # Examples: # OUTPUTDIR="/myoutputdir" #----------------------------------------------------------------------------- OUTPUTDIR = "./output" # Directory where to store result output file(s) SERVER = "www.mysite.com" # Domain name of main server to test (www.mysite.com) #USER = "test" # If your web application require a Basic authentication, this is the login that awbot will use for this test session #PASSWORD = "test" # If your web application require a Basic authentication, this is the password that awbot will use for this test session #PROXYSERVER = "http://my.proxy.server:port/" # If the web application to test is after a proxy BOTNAME = "AWBot" # String value to force bot name used in the user agent string DELAY = 0 # Delay beetween each HTTP request (-1 wait a key, 0 no delay, n number of seconds) MAXSIZE = 0 # Maximum size of HTTP response (0 = no limit) TIMEOUT = 120 # Timeout (when waiting for a server response after sending a request) LANG = "fr" # Choose output language # DATABASE PARAMETERS SECTION #----------------------------------------------------------------------------- # This section is required only if you added SQL requests in your ACTIONS section (see later) # # Examples: # BASEENGINE="mysql" # USERBASE=($USER eq "toto"?"titi":$USER) #----------------------------------------------------------------------------- #BASEENGINE = "Oracle" # Here is the name of the perl DBD driver (mysql, ODBC, Oracle, Sybase...) #DSN = "mybase" # Database name #USERBASE = "myuser" # Database login #PASSWORDBASE = "mypassword" # Database password # OTHER PARAMETERS SECTION #----------------------------------------------------------------------------- # You can add here as many parameters as you need for rest of config file. # Just use the following syntax (where n is a number between 1 and 99): # PARAMn=value # PARAMn="SELECT SQL request" # # Examples: # PARAM1="select id from employee where name='$USER'" # PARAM2=2000+$PARAM1 #----------------------------------------------------------------------------- PARAM1 = 1 # LIST OF ACTIONS TO EXECUTE BEFORE A TEST #----------------------------------------------------------------------------- # You can use one of the keyword: # SEQUENCE To set a database sequence to a value (see examples, for Oracle only) # SQL To delete/insert some records in the database (see examples) # SCRIPT To launch an external script # # Examples: # SEQUENCE "myseq" $PARAM3+1 # SQL "delete from customers where id_customers < ".($PARAM1+$PARAM2) # SCRIPT "myscript.exe" #----------------------------------------------------------------------------- <PRE ACTIONS> </PRE ACTIONS> # LIST OF ORDERED URLS TO TEST #----------------------------------------------------------------------------- # Use the following format: # GET To get an HTML page (using GET HTTP method, like HTML links) # POST To get an HTML page (using POST HTTP method, like HTML forms) # CHECKYES To check if string is found in last response (using POSIX regex) # CHECKNO To check if a string is not found in last response (using POSIX regex) # VAR To extract a parameter from last response (using POSIX regex) # SEQUENCE To set a database sequence to a value (see examples, for Oracle only) # SQL To delete/insert some records in the database (see examples) # SCRIPT To launch an external script # WRITETO Write last html response to a file # WRITETOH Write last html response with its HTTP header to a file (full response) # AUTO To make a GET on all URLs find in last HTML response page and follow # links on n level # # Examples: # GET "http://$SERVER/mypage.html?x=y&v=w" # POST "http://$SERVER/mypage.html?x=y&v=w" # CHECKYES "xxx" # CHECKNO "eee" # VAR "VARNAME:idvar=(\d)" # AUTO 1 # SEQUENCE "myseq" $PARAM3+1 # SQL "delete from customers" # SCRIPT "myscript.exe" # WRITETO "myfile.html" # WRITETOH "myfile.http" #----------------------------------------------------------------------------- <ACTIONS> GET "http://$SERVER/" </ACTIONS> # LIST OF ACTIONS TO EXECUTE AFTER A TEST #----------------------------------------------------------------------------- # You can use same rules for LIST OF ACTIONS TO EXECUTE BEFORE A TEST. #----------------------------------------------------------------------------- <POST ACTIONS> </POST ACTIONS>

First this is an index of all directives available for each part of config/test file :

INIT PARAMETERS

OUTPUTDIR
SERVER
USER
PASSWORD
PROXYSERVER
BOTNAME
DELAY
MAXSIZE
TIMEOUT

DATABASE PARAMETERS (Required if you need pre-post SQL commands)

DATABASE
DSN
USERBASE
PASSWORDBASE

OTHER PARAMETERS

PARAMdd

LIST OF ACTIONS TO EXECUTE BEFORE A TEST

SEQUENCE
SQL
SCRIPT

LIST OF URLS TO TEST

GET
POST
CHECKYES
CHECKNO
VAR
SEQUENCE
SQL
SCRIPT
WRITETO
WRITETOH

LIST OF ACTIONS TO EXECUTE AFTER A TEST

Same directives than for LIST OF ACTIONS TO EXECUTE BEFORE A TEST are available.

INIT PARAMETERS

OUTPUTDIR
Version : 1.0 +
Syntax :
OUTPUTDIR="./myoutput"
Examples :
OUTPUTDIR="./myoutput"
Explanation :
This directive contains the name of directory where AWBot will
store all output files (results of tests).

SERVER
Version : 1.0 +
Syntax :
SERVER="/var/log/httpd/mylog.log"
Examples :
SERVER="www.mysite.com"
SERVER="myintranetserver"
SERVER="127.0.0.1"
Explanation :
This directive contains the name of server to test.
Note that this directive will be ignored if server name to test is provided on command line with -server option when launching AWBot.

USER
Version : 1.0 +
Syntax :
USER="username"
Examples :
USER="john"
Explanation :
This directive contains the name of the user to use to access pages that require a Basic HTTP authentication.
Note that this directive will be overwrited if user is provided on command line with -user option when launching AWBot.

PASSWORD
Version : 1.0 +
Syntax :
PASSWORD="password"
Examples :
PASSWORD="a12QioP_e"
PASSWORD="$USER"
Explanation :
This directive contains the name of the password to use to access pages that require a Basic HTTP authentication.
Note that this directive will be overwrited if password is provided on command line with -password option when launching AWBot.

PROXYSERVER
Version : 1.1 +
Syntax :
PROXYSERVER="http://my.proxy.server:port/"
Examples :
PROXYSERVER="http://myproxy.server:8080/"
Explanation :
If the web application to test is after a proxy.

BOTNAME
Version : 1.0 +
Syntax :
BOTNAME="bot name"
Examples :
BOTNAME="AWBot"
Explanation :
This directive contains the name of the User Agent that AWBot will use as its browser name.
This data might only appear is the web server log file.

DELAY
Version : 1.0 +
Syntax :
DELAY=d
Examples :
DELAY=-1
DELAY=0
DELAY=5
Explanation :
Between each URL request, you can ask AWBot to wait a certain number of time. Use this directive to give this time in number of seconds:

d Means AWBot will wait d seconds (after receiving a HTTP page) before sending next HTTP request.

0 Means AWBot will never wait (There is always a running request).

-1 Means AWBot will wait a key pressed on console that run the bot.

Note that this directive will be overwrited if delay is provided on command line with -delay option when launching AWBot.

MAXSIZE
Version : 1.0 +
Syntax :
MAXSIZE=d
Examples :
MAXSIZE=0
MAXSIZE=524288
Explanation :
This directive is rarely used. If you really need to "cut" a HTTP page to its first MAXSIZE octets, you can set this parameter. In most cases, use MAXSIZE=0 to always get there entire page.

TIMEOUT
Version : 1.0 +
Syntax :
TIMEOUT=d
Examples :
TIMEOUT=120
Explanation :
This directive contains the time-out used when AWbot is waiting a page after requesting a page.
This is a number of seconds. Traditionnal browsers have a such time-out set between 120 and 300.

DATABASE PARAMETERS

DATABASE
Version : 1.0 +
Syntax :
DATABASE=mysql
Examples :
DATABASE=mysql
DATABASE=ODBC
DATABASE=Oracle
DATABASE=Sybase
Explanation :
This directive contains the name of DBD modules you need to use if you want ot make direct database actions by the bot.
! Note that dbd and dbi perl modules are not enabled in bot by default. So if you need to use database features, don't forget to uncomment the line corresponding to your database in awbot.pl file and don't forget to install the dbd and dbi perl modules (if not available by default with your perl).
#__START_OF_SGBD_SETUP
#use DBD::Oracle;
#use DBD::Sybase;
#use DBD::ODBC;
#use DBD::mysql;
#__END_OF_SGBD_SETUP

DSN
Version : 1.0 +
Syntax :
DSN=mydatabasename
Examples :
DSN=test
Explanation :
This parameter contains the name of the database you want to make direct requests on.

USERBASE
Version : 1.0 +
Syntax :
USERBASE=user
Examples :
USERBASE=john
Explanation :
This parameter contains the database login used to connect to the database you want to make direct requests on.

PASSWORDBASE
Version : 1.0 +
Syntax :
DSN=mypassword
Examples :
DSN=gandalf
Explanation :
This parameter contains the database password used to connect to the database you want to make direct requests on.

OTHER PARAMETERS

PARAMdd
Version : 1.0 +
Syntax :
PARAMdd=value
Examples :
PARAM01=paris
PARAM02=houston
Explanation :
This directive allows to define constant parameters that can be use in all other directives.

LIST OF URLS TO TEST

GET
Version : 1.0 +
Syntax :
GET "http://$SERVER/mypage.html?x=y&v=w"
Examples :
GET "http://$SERVER/"
GET "http://$SERVER/cgi-bin/myscript.cgi?town=$PARAM01"
GET "http://$SERVER/customer_$CUSTID.php"
Explanation :
Add a line with GET command to ask the bot to get page/url returned by server after a request defined by the second parameter (using GET HTTP method, like HTML links).

POST
Version : 1.0 +
Syntax :
GET "http://$SERVER/mypage.cgi?x=y&v=w"
Examples :
GET "http://$SERVER/cgi-bin/sendmail.pl?email=jo@jomail.com&subject=hello%20from%20$PARAM02&text=how%20are%20you"
Explanation :
Add a line with POST command to ask the bot to get page/url returned by server after a request defined by the second parameter (using POST HTTP method, like HTML forms).
Note that you declare forms parameter like you do for a GET (with "?x=y&v=w..."), the bot will convert them to send a HTTP request with the correct POST protocol.

CHECKYES
Version : 1.0 +
Syntax :
CHECKYES "regex"
Examples :
CHECKYES "welcome"
Explanation :
The bot check in the last page/url response after a GET or POST command that the received HTML page contains a particular pattern in it.
You can use a required matching text or any regexp expression.
If value is not found the bot, will return an error and will stop the process (except if -nostopiferror was provided in command line when launching the bot).
The opposite of CHECKYES is CHECKNO
.

CHECKNO
Version : 1.0 +
Syntax :
CHECKNO "regex"
Examples :
CHECKNO "error"
Explanation :
The bot check in the last page/url response after a GET or POST command that the received HTML page does not contain a particular pattern in it.
You can use a required matching text or any regexp expression.
If value is found, the bot will return an error and will stop the process (except if -nostopiferror was provided in command line when launching the bot).

VAR
Version : 1.0 +
Syntax :
VAR "VARNAME:idvar=(\d)"
Examples :
VAR "CUSTID:your customer id is (\d+)"
Explanation :
This command ask the bot to extract a dat in the last page/url receive HTML page, after a GET or POST command, and store the extracted data into a variable called CUSTID.
You can send reuse this value into any of following command using the '$CUSTID' variable.
To extract a particular value from a received HTML page you must provide after the ':', a string (or regexp pattern) that exists in this page and use a regex pattern between ( and ) to tell which value will be stored in the $CUSTID parameter.

SEQUENCE
Version : 1.0 +
SEQUENCE "sequencename" value
Examples :
SEQUENCE "myseq" $PARAM3+1
This command can only works for Oracle database. It sets a particular Oracle sequence to a particular value.
This command can only be used if the DBD perl module has been enabled in the bot.

SQL
Version : 1.0 +
Syntax :
SQL "sqlrequest"
Examples :
SCRIPT "DELETE FROM CUSTOMERS where ID=$CUSTID"
SCRIPT "INSERT INTO TOWN(name,id) values($PARAM01,$STARTSESSION)"
Explanation :
When the bot meet this directive, it executes the SQL requests on the database defined by DATABASE and DSN parameters in DATABASE section.
Note that if you have several SQL commands in a config/test file, the bot will only connect once to the database.
This command can only be used if the DBD perl module has been enabled in the bot.

SCRIPT
Version : 1.0 +
Syntax :
SCRIPT "scriptname"
Examples :
SCRIPT "/home/test/dummy.ksh"
Explanation :
When the bot meet this directive, it runs the given external scripts. The bot waits the end of it before reading the next command and continue its process.

WRITETO
Version : 1.0 +
Syntax :
WRITETO "filetowriteinto"
Examples :
CHECKNO "snapshot.html"
Explanation :
When the bot meet this directive, it writes the content of the last page/url response received after last GET or POST command into a file.

WRITETOH
Version : 1.0 +
Syntax :
WRITETOH "filetowriteinto"
Examples :
WRITETOH "snapshot.http"
Explanation :
When the bot meet this directive, it writes the content of the last page/url response with its HTTP header, received after last GET or POST command, into a file.