X-Git-Url: http://git.pk910.de/?p=ircu2.10.12-pk.git;a=blobdiff_plain;f=tests%2Freadme.txt;fp=tests%2Freadme.txt;h=98466d186766e987b61c339ca370c5a04e4d5bc3;hp=0000000000000000000000000000000000000000;hb=0400a5a6479398d82526785c18c0df8bc8b92dce;hpb=d17e10da972ce5776c60b4c317267c6abe0e1ead

diff --git a/tests/readme.txt b/tests/readme.txt
new file mode 100644
index 0000000..98466d1
--- /dev/null
+++ b/tests/readme.txt
@@ -0,0 +1,107 @@
+ircu Test Framework
+===================
+
+This directory contains a simple test driver for ircu, supporting
+files, and test scripts.  test-driver.pl requires the POE and
+POE::Component::IRC modules for Perl; they are available from CPAN.
+
+The test scripts assume that an instance of ircu has been started
+using the ircd.conf file in this directory (e.g. by running
+"../ircd/ircd -f `pwd`/ircd.conf"), and that IPv4 support is enabled
+on the system.
+
+The test-driver.pl script accepts several command-line options:
+
+ -D enables POE::Component::IRC debugging output
+ -V enables test-driver.pl debugging output
+ -Hipaddr sets the IPv4 address to use for connections to the server
+ one or more script names to interpret and execute
+
+The normal output is one dot for each line that is executed.  Using
+the -D and -V options generates much more output.
+
+Command Syntax
+==============
+
+A test script typically starts with a set of variable definitions for
+strings that are used throughout the script or that may be changed to
+match changes ircu's configuration file.  These have the syntax:
+	define <variable> <replacement text>
+
+A variable is expanded by writing %variablename% in later commands.
+If a variable is dereferenced without a definition, the test will
+abort.
+
+Following the variable definitions is usually one or more "connect"
+statements.  These have the syntax:
+	connect <tag> <nickname> <username> <server:port> :<Real Name or GECOS>
+This creates a client and starts a connection to an IRC server.  The
+tag is used to issue commands for that client in the rest of the file.
+The remaining fields have their usual meanings for IRC.
+
+A number of IRC commands are supported natively, including:
+	:<tag> join <channel>
+	:<tag> mode <nick/channel> [<modes> ...]
+	:<tag> nick <nickname>
+	:<tag> notice <target> :<text>
+	:<tag> oper <name> <password>
+	:<tag> part <channel> [:<message>]
+	:<tag> privmsg <target> :<text>
+	:<tag> quit [:<message>]
+	:<tag> raw :<irc line to send>
+
+Other commands are used to implement tests:
+	:<tag> expect <irc line contents>
+	:<tag> sleep <seconds>
+	:<tag> wait <tag2,tag3>
+
+The test commands are discussed at more length below.
+
+expect Syntax
+=============
+
+The command to look for data coming from the irc server is "expect":
+	:<tag> expect <irc line contents>
+
+The contents are treated as a regular expression and matched against
+the start of the line.  If the line from the IRC server began with
+':', that is removed before the match is performed.
+
+Because the contents are a regular expression, and because \ is used
+as an escape character both in parsing both the script line and the
+regular expression, some common things become awkward to match:
+	:cl1 mode %channel% +D
+	:cl1 expect %cl1-nick% mode %channel% \\+D
+or a more drastic example:
+	:cl1 mode %channel% +b *!*@*.bar.example.*
+	:cl1 mode %channel% +b
+	:cl1 expect %srv1-name% 367 %channel% \\*!\\*@\\*\\.bar\\.example\\.* %cl1-nick% \\d+
+
+sleep Syntax
+============
+
+The command to make a client stop operating for a fixed period of time
+is "sleep":
+	:<tag> sleep <seconds>
+
+This will deactivate the identified client for at least <seconds>
+seconds (which may be a floating point number).  Other clients will
+continue to process commands, but if another command for the
+identified client is encountered, it will block execution until the
+time expires.
+
+wait Syntax
+===========
+
+The command to synchronize one client to another is "wait":
+	:<tag> wait <tag2[,tag3...]>
+
+This is syntactic sugar for something like this:
+	:<tag> expect <nick2> NOTICE <nick> :SYNC
+	:<nick2> notice <nick> :SYNC
+	:<tag> expect <nick3> NOTICE <nick> :SYNC
+	:<nick3> notice <nick> :SYNC
+
+In other words, the wait command uses in-IRC messages to make sure
+that other clients have already executed commands up to a certain
+point in the test script.