tests/readme.txt

   1 ircu Test Framework
   2 ===================
   3
   4 This directory contains a simple test driver for ircu, supporting
   5 files, and test scripts.  test-driver.pl requires the POE and
   6 POE::Component::IRC modules for Perl; they are available from CPAN.
   7
   8 The test scripts assume that an instance of ircu has been started
   9 using the ircd.conf file in this directory (e.g. by running
  10 "../ircd/ircd -f `pwd`/ircd.conf"), and that IPv4 support is enabled
  11 on the system.
  12
  13 The test-driver.pl script accepts several command-line options:
  14
  15  -D enables POE::Component::IRC debugging output
  16  -V enables test-driver.pl debugging output
  17  -Hipaddr sets the IPv4 address to use for connections to the server
  18  one or more script names to interpret and execute
  19
  20 The normal output is one dot for each line that is executed.  Using
  21 the -D and -V options generates much more output.
  22
  23 Command Syntax
  24 ==============
  25
  26 A test script typically starts with a set of variable definitions for
  27 strings that are used throughout the script or that may be changed to
  28 match changes ircu's configuration file.  These have the syntax:
  29         define <variable> <replacement text>
  30
  31 A variable is expanded by writing %variablename% in later commands.
  32 If a variable is dereferenced without a definition, the test will
  33 abort.
  34
  35 Following the variable definitions is usually one or more "connect"
  36 statements.  These have the syntax:
  37         connect <tag> <nickname> <username> <server:port> :<Real Name or GECOS>
  38 This creates a client and starts a connection to an IRC server.  The
  39 tag is used to issue commands for that client in the rest of the file.
  40 The remaining fields have their usual meanings for IRC.
  41
  42 A number of IRC commands are supported natively, including:
  43         :<tag> join <channel>
  44         :<tag> mode <nick/channel> [<modes> ...]
  45         :<tag> nick <nickname>
  46         :<tag> notice <target> :<text>
  47         :<tag> oper <name> <password>
  48         :<tag> part <channel> [:<message>]
  49         :<tag> privmsg <target> :<text>
  50         :<tag> quit [:<message>]
  51         :<tag> raw :<irc line to send>
  52
  53 Other commands are used to implement tests:
  54         :<tag> expect <irc line contents>
  55         :<tag> sleep <seconds>
  56         :<tag> wait <tag2,tag3>
  57
  58 The test commands are discussed at more length below.
  59
  60 expect Syntax
  61 =============
  62
  63 The command to look for data coming from the irc server is "expect":
  64         :<tag> expect <irc line contents>
  65
  66 The contents are treated as a regular expression and matched against
  67 the start of the line.  If the line from the IRC server began with
  68 ':', that is removed before the match is performed.
  69
  70 Because the contents are a regular expression, and because \ is used
  71 as an escape character both in parsing both the script line and the
  72 regular expression, some common things become awkward to match:
  73         :cl1 mode %channel% +D
  74         :cl1 expect %cl1-nick% mode %channel% \\+D
  75 or a more drastic example:
  76         :cl1 mode %channel% +b *!*@*.bar.example.*
  77         :cl1 mode %channel% +b
  78         :cl1 expect %srv1-name% 367 %channel% \\*!\\*@\\*\\.bar\\.example\\.* %cl1-nick% \\d+
  79
  80 sleep Syntax
  81 ============
  82
  83 The command to make a client stop operating for a fixed period of time
  84 is "sleep":
  85         :<tag> sleep <seconds>
  86
  87 This will deactivate the identified client for at least <seconds>
  88 seconds (which may be a floating point number).  Other clients will
  89 continue to process commands, but if another command for the
  90 identified client is encountered, it will block execution until the
  91 time expires.
  92
  93 wait Syntax
  94 ===========
  95
  96 The command to synchronize one client to another is "wait":
  97         :<tag> wait <tag2[,tag3...]>
  98
  99 This is syntactic sugar for something like this:
 100         :<tag> expect <nick2> NOTICE <nick> :SYNC
 101         :<nick2> notice <nick> :SYNC
 102         :<tag> expect <nick3> NOTICE <nick> :SYNC
 103         :<nick3> notice <nick> :SYNC
 104
 105 In other words, the wait command uses in-IRC messages to make sure
 106 that other clients have already executed commands up to a certain
 107 point in the test script.