# HG changeset patch # User Matthew Wild # Date 1549020140 0 # Node ID 5d39804f108b8abfef7bbab9dc4f9acafbab92b8 # Parent 92e1733243d5dd95cf5182f2e78e953b6a1ddf96 docs: Add initial documentation diff -r 92e1733243d5 -r 5d39804f108b docs/character-classes/client.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/character-classes/client.md Fri Feb 01 11:22:20 2019 +0000 @@ -0,0 +1,92 @@ +# Client: XMPP client + +The `[Client]` class represents an XMPP client connection to a server. + +Example: + +``` +[Client] Romeo + jid: romeo@example.com + password: s3cr3t! +``` + + +## Properties + +| Property | Description | +|:-------------|:------------------------------------| +| jid | The JID to connect to the server as | +| password | The password to connect with | +| connect_host | The server host, if not the default | +| connect_port | The server port, if not the default | + +## Actions + +### sends + +Sends a stanza to the XMPP server. + +Example: + +``` +Romeo sends: + + + +``` + +### receives + +Expects to receive a stanza from the server. + +Example: + +``` +Romeo receives: + + + + + +``` + +If no stanza is expected, the simple string 'nothing' may be used: + +``` +Romeo receives: nothing +``` + +#### Matching rules + +When a stanza is received from the server, it is matched against the one in the script. +If it does not match, the script will fail and abort. + +The matching has two modes, strict and non-strict. They require: + +Non-strict mode: + +- All attributes in the expected stanza must be present in the received stanza. Additional +attributes in the received stanza are ignored. +- All tags in the expected stanza must be present in the received stanza. Additional tags are ignored. Order is ignored. + +Strict mode: + +- All attributes in the expected stanza must be in the received stanza, and vice-versa. Additional attributes in the received stanza are not allowed. +- All tags in the expected stanza must be in the received stanza, additional tags are not allowed. Order must be the same. + +Both modes: + +- If an attribute value is `{scansion:any}` in the expected stanza, that attribute must be present in the received stanza, but +the value itself is ignored. This is useful for e.g. id attributes or other attributes that may vary unpredictably. + +By default tags in the default namespace are matched using the non-strict rules, but tags with their own namespace are matched using the +strict rules. You can override the matching behaviour for any tag by adding a `scansion:strict` attribute with a value of `true` or `false`: + +``` +# By default this would match any message, by ignoring +# extra payloads. However we enable strict mode to ensure +# that it only matches a completely empty message stanza: + +Romeo receives: + +``` diff -r 92e1733243d5 -r 5d39804f108b docs/index.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.md Fri Feb 01 11:22:20 2019 +0000 @@ -0,0 +1,66 @@ +# Scansion - Automated XMPP Client + +Scansion is an automated scriptable XMPP client, useful for testing and +automating tasks. It is primarily designed to be a handy tool in an XMPP +developer's toolbox, however its scripting language is designed to be easy +to read and write by non-programmers who understand basic XML and XMPP. + +An example Scansion script: + +```xml +# Pubsub: Test node creation + +[Client] Romeo + jid: admin@localhost + password: password + +[Client] Juliet + jid: juliet@localhost + password: password + +--------- + +Romeo connects + +# Create the node +Romeo sends: + + + + + + +# Server acknowledges successful creation +Romeo receives: + + +# Juliet sees the node appear in the node list + +Juliet connects + +Juliet sends: + + + + +Juliet receives: + + + + + + +# Yay! + +``` + +This example demonstrates how Scansion: + +- Supports multiple characters in a script +- Takes care of establishing a connection and authentication +- Automatically verifies responses to stanzas + +This final point is what makes Scansion a great tool for testing - it +has a flexible matching system that allows you to ensure a certain stanza +receives the response you expect. + diff -r 92e1733243d5 -r 5d39804f108b docs/install.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/install.md Fri Feb 01 11:22:20 2019 +0000 @@ -0,0 +1,46 @@ +## Installation and setup + +### Requirements + +Scansion requires: + +- Lua 5.2 +- Verse (a version is bundled by default) +- LuaExpat +- LuaCJSON +- LuaSec +- LuaSocket +- LuaFileSystem (optional) + +If these are present, a simple 'make' and 'sudo make install' should suffice to install scansion to `/usr/local/bin/`. + +On Debian and Ubuntu, these can be installed with the following command: + +``` +apt install lua5.2 lua-expat lua-cjson lua-sec lua-socket lua-filesystem +``` + +### Docker + +A Dockerfile is also provided, to allow you to build and run scansion inside a clean environment with all dependencies +installed already. + +First, build the image: + +``` +docker build -t scansion . +``` + +To run it with a directory of test scripts in ./spec/scansion: + +``` +docker run -v$PWD/spec/scansion:/scripts scansion +``` + +To run it [as a service](usage/service.md): + +``` +docker run -p 8007:8007 -v$PWD/spec/scansion:/scripts scansion --serve + +``` + diff -r 92e1733243d5 -r 5d39804f108b docs/usage/script-basics.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/usage/script-basics.md Fri Feb 01 11:22:20 2019 +0000 @@ -0,0 +1,62 @@ +# Script basics + +Scansion scripts are designed to be extremely easy to read and write. They are based +on natural language statements as far as possible. + +## Metadata + +A script begins with an optional title and description: + +``` +# Script Title +# A short description of the script. +``` + +Scripts may also contain one or more tags. A tag is either a simple string or +may also include an associated value. They are one tag per line, each beginning +with `##`: + +``` +## slow +## status: stable +``` + +Tags are useful to group scripts, and allow you to easily filter when running +Scansion with many scripts at once, e.g. with `--only-tags "status: stable"` or +`--skip-tags slow`. + +## Defining characters + +Every script defines one or more characters that will perform actions in the +script. + +Definitions consist of the type and name of the character, as well as any additional +properties specific to that character. + +For example, an XMPP client called Romeo might be defined like this: + +``` +[Client] Romeo + jid: romeo@example.com + password: s3cr3t! +``` + +## Actions + +Once you have defined characters, you can have them perform actions. For example +our client Romeo will connect to the server and broadcast his availability to +contacts: + +``` +Romeo connects + +# Send presence! +Romeo sends: + +``` + +Different types of characters support different actions, see for example the +[Client class](../character-classes/client.md). + +Note: lines beginning with a '#' are comments, and are useful to add descriptions to +each action, and help keep scripts readable. diff -r 92e1733243d5 -r 5d39804f108b docs/usage/service.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/usage/service.md Fri Feb 01 11:22:20 2019 +0000 @@ -0,0 +1,7 @@ +# Running as a service + +**This is an early-stage feature that is still being developed, and is subject to change.** + +Scansion, if built with --with-server (the default), may be run as a service. +It provides a /run endpoint over HTTP, which may be provided with a script to +run. After completion, it returns the result.