diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 112 |
1 files changed, 0 insertions, 112 deletions
@@ -1,112 +0,0 @@ -# -*- mode: org -*- - -* Overview -A test consists of a config file, which specifies variables available -during the execution of the test, a test plan file, which dictates the -order of the test, and a series of templates, referenced by the test -plan, which contain the data to be read and optionally matched. See -the Testing section for an example of how to use it. - -This is intended to be used for request-response style interactions, -where we send a request and wait for a matching response. However, not -all requests stimulate a response, so response matching is optional. - -By default this program reads from standard input and writes to -standard output, but if a command line is supplied as the final -arguments, that will be used instead. This is useful with netcat for -network server testing. - -* Config File -The format of the config file is a list of arbitrary '$key=$value' -pairs. Comments start with '#' and continue until the end of the line. - -Config keys are auto-interned as nullary functions for use in -templates. - -* Test Plan -The test plan file is a list of files to run within the templates -directory (which defaults to 'xml'), suffixed by '.xml' for sending -data, and, if it exists, suffixed by '.expected.xml' for matching -responses. Thus a test plan line which consists of 'foo' would send -data according to the template in 'xml/foo.xml' and would then wait -for data matching the template in 'xml/foo.expected.xml' if that file -exists. - -The XML stuff is not ideal, since this program doesn't care about the -format of the data being read or written, but since it was developed -for XMPP testing, that's what it got. This may change in the future. - -* Templates -Templates are fundamentally a big regexp with thunks of Perl code -contained within '{}' interpolated at run-time. While templates are -used for both sending data and matching received data, the use of -thunks changes depending on context. - -** Send context -In send context (e.g., 'foo.xml'), the code called may return a string -which will replace the thunk in the template. Assuming you have a -function defined called bar: -#+BEGIN -sub bar() { "text" }; -#+END - -and a template: -#+BEGIN -Here is some {bar}! -#+END - -The output would be: -#+BEGIN -Here is some text! -#+END - -The code is arbitrary Perl 5, and doesn't have to return a string, but -if it returns anything it should be something that can be converted to -a string automatically, or you're likely to get an error. - -** Match context -During matching, the template is processed as a regexp, where thunks -are treated as captured wildcards (i.e., the pattern '(.*)'). After a -successful match, the value of the capture is made available to the -thunk in the $arg variable. This is so that the value can be compared -with an expected value, or that more complex computation can be done -(such as for challenge-response authentication). - -It is assumed that there will be cases where data that you're not -interested in can be interleaved in data that you are interested in -(e.g., keepalives) and match templates will ignore them. - -** Evaluation package -Templates are evaluated in their own package, outside of main, to -better isolate their side-effects. Some package-level globals are made -available: - * $in - The filehandle we're reading match data from. - * $out - The filehandle we're sending data to. - * %env - The key-value pairs from the loaded config file. - * $arg - The value of the capture group for this thunk (in match - context) - -This package is never reinitialized during the test plan execution, -allowing one template to modify data for subsequent templates. - -** XML -In order to make XML processing easier any type of quote, throughout -the text, is turned into the pattern ['"] during match -context. Similarly, whitespace is condensed and replaced with the \s* -pattern. - -Do note that while this program is intended to be used primarily with -XML, it's almost totally ignorant of XML as a format besides the above -substitutions. That means that things like attribute order within a -tag matter, and we cannot normalize '<foo></foo>' to '<foo/>' (at -least unless you write a big tangle of regexp in the template itself). - -* Testing -The file 'testplan' contains a sample plan for a basic XMPP session -given 'localhost.conf', using the files in the 'xml' directory. The -corresponding server data is in 'input'. So to run a quick-and-dirty -test, execute: - -#+BEGIN -% xmpt -e t/fixtures/sample.env -p t/fixtures/sample.plan < t/fixtures/sample.input -#+END |