Mercurial > scansion / changeset

--- /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:
+	<iq type="get" id="123">
+		<query xmlns="jabber:iq:roster"/>
+	</iq>
+```
+
+### receives
+
+Expects to receive a stanza from the server.
+
+Example:
+
+```
+Romeo receives:
+	<iq type="result" id="123">
+		<query xmlns="jabber:iq:roster">
+			<item jid="juliet@example.com" subscription="both" />
+		</query>
+	</iq>
+```
+
+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:
+	<message scansion:strict="true"/>
+```

--- /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:
+	<iq type='set' to='pubsub.localhost' id='create-node'>
+		<pubsub xmlns='http://jabber.org/protocol/pubsub'>
+			<create node='princely_musings'/>
+		</pubsub>
+	</iq>
+
+# Server acknowledges successful creation
+Romeo receives:
+	<iq type='result' id='create-node'/>
+
+# Juliet sees the node appear in the node list
+
+Juliet connects
+
+Juliet sends:
+	<iq type='get' id='list-nodes' to='pubsub.localhost'>
+		<query xmlns='http://jabber.org/protocol/disco#items'/>
+	</iq>
+
+Juliet receives:
+	<iq type='result' id='list-nodes' from='pubsub.localhost'>
+		<query xmlns='http://jabber.org/protocol/disco#items'>
+			<item xmlns='http://jabber.org/protocol/disco#items' jid='pubsub.localhost' node='princely_musings'/>
+		</query>
+	</iq>
+
+# 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.
+

--- /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
+
+```
+

--- /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:
+	<presence/>
+```
+
+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.

--- /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.