imip-agent

Annotated docs/wiki/Testing

1154:08f6668e1374
1136:ba4b2c8fbc35
2016-04-22 Paul Boddie file changeset files shortlog Propagated messages to the different translation files.
paul@955 1 
= Testing =
paul@955 2 
 
 paul@989      3 
Before attempting to integrate imip-agent with other system components,
 
 paul@989      4 
it can be useful to check whether the different programs function as
 
 paul@989      5 
expected by themselves. Should errors or faults occur, these would need
 
 paul@989      6 
to be remedied first before attempting to get the software working with
 
 paul@1011      7 
the [[../MailIntegration|mail]] and [[../WebServerIntegration|Web]]
 
 paul@1011      8 
system components.
 
 paul@989      9 
 
 paul@989     10 
<<TableOfContents(2,2)>>
 
 paul@989     11 
 
 paul@989     12 
== How the Software Works ==
 
 paul@989     13 
 
 paul@955     14 
To see how the software operates, you can run one of the agent programs
 
 paul@955     15 
provided in the distribution. For example:
 
 paul@955     16 
 
 paul@955     17 
{{{
 
 paul@955     18 
./imip_resource.py -S xxx/store -P xxx/static -p xxx/prefs -d \
 
 paul@955     19 
  < tests/templates/event-request.txt
 
 paul@955     20 
}}}
 
 paul@955     21 
 
 paul@955     22 
This uses one of the test files, sending it to the agent program for
 
 paul@955     23 
resource entities, producing output resembling the following:
 
 paul@955     24 
 
 paul@955     25 
{{{
 
 paul@955     26 
Outgoing parts for paul.boddie@example.com...
 
 paul@955     27 
From nobody Wed Oct 28 00:24:41 2015
 
 paul@955     28 
MIME-Version: 1.0
 
 paul@955     29 
Content-Transfer-Encoding: base64
 
 paul@955     30 
Content-Type: text/calendar; charset="utf-8"; method="REPLY"
 
 paul@955     31 
From: calendar@example.com
 
 paul@955     32 
To: paul.boddie@example.com
 
 paul@955     33 
Subject: Calendar system message
 
 paul@955     34 
 
 paul@955     35 
QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVQTFkNClZFUlNJT046Mi4wDQpCRUdJTjpWRlJFRUJV
 
 paul@955     36 
U1kNCk9SR0FOSVpFUjptYWlsdG86cGF1bC5ib2RkaWVAZXhhbXBsZS5jb20NCkFUVEVOREVFO1NF
 
 paul@955     37 
TlQtQlk9Im1haWx0bzpjYWxlbmRhckBleGFtcGxlLmNvbSI6bWFpbHRvOnJlc291cmNlLXJvb20t
 
 paul@955     38 
Y29uZnJvb20NCiBAZXhhbXBsZS5jb20NClVJRDpmYjFAZXhhbXBsZS5jb20NCkVORDpWRlJFRUJV
 
 paul@955     39 
U1kNCkVORDpWQ0FMRU5EQVINCg==
 
 paul@955     40 
}}}
 
 paul@955     41 
 
 paul@955     42 
The rather opaque encoding can be inspected using the `tools/showmail.py`
 
 paul@955     43 
program, and thus the result of the script can be seen by piping the output
 
 paul@955     44 
through that program as follows:
 
 paul@955     45 
 
 paul@955     46 
{{{
 
 paul@955     47 
./imip_resource.py -S xxx/store/ -P xxx/static/ -p xxx/prefs/ -d \
 
 paul@955     48 
  < tests/templates/event-request.txt \
 
 paul@955     49 
  | tools/showmail.py
 
 paul@955     50 
}}}
 
 paul@955     51 
 
 paul@955     52 
The result should resemble the following:
 
 paul@955     53 
 
 paul@955     54 
{{{
 
 paul@955     55 
Outgoing parts for paul.boddie@example.com...
 
 paul@955     56 
MIME-Version: 1.0
 
 paul@955     57 
Content-Type: text/calendar; charset="utf-8"; method="REPLY"
 
 paul@955     58 
From: calendar@example.com
 
 paul@955     59 
To: paul.boddie@example.com
 
 paul@955     60 
Subject: Calendar system message
 
 paul@955     61 
 
 paul@955     62 
BEGIN:VCALENDAR
 
 paul@955     63 
METHOD:REPLY
 
 paul@955     64 
VERSION:2.0
 
 paul@955     65 
BEGIN:VEVENT
 
 paul@955     66 
DTSTAMP:20151027T232738Z
 
 paul@955     67 
UID:event1@example.com
 
 paul@955     68 
ATTENDEE;PARTSTAT=ACCEPTED;SENT-BY="mailto:calendar@example.com":mailto:reso
 
 paul@955     69 
 urce-room-confroom@example.com
 
 paul@955     70 
SUMMARY:Meeting at 4pm
 
 paul@955     71 
ORGANIZER:mailto:paul.boddie@example.com
 
 paul@955     72 
DTSTART;TZID=Europe/Oslo:20141126T160000
 
 paul@955     73 
DTEND;TZID=Europe/Oslo:20141126T170000
 
 paul@955     74 
END:VEVENT
 
 paul@955     75 
END:VCALENDAR
 
 paul@955     76 
}}}
 
 paul@955     77 
 
 paul@955     78 
What has happened here is the presentation of a request to the resource
 
 paul@955     79 
program in the form of an e-mail message containing an iCalendar event
 
 paul@955     80 
employing a scheduling method. The program interprets the request,
 
 paul@955     81 
consults its own records, makes a decision about scheduling the event,
 
 paul@955     82 
and indicates the kind of response it would like to send back to the
 
 paul@955     83 
requester.
 
 paul@989     84 
 
 paul@989     85 
== The Test Suite ==
 
 paul@989     86 
 
 paul@989     87 
A script called `test_all.sh` is provided that runs a test suite (found
 
 paul@989     88 
in the `tests` directory within the source code distribution), initialising
 
 paul@989     89 
new and separate data store instances for each test, running programs that
 
 paul@989     90 
are presented with message content, and testing for the desired effects of
 
 paul@989     91 
running those programs with such content.
 
 paul@989     92 
 
 paul@1102     93 
{{{
 
 paul@1102     94 
./test_all.sh
 
 paul@1102     95 
}}}
 
 paul@1102     96 
 
 paul@1136     97 
The test suite by default (or by indicating `file` as the data store type),
 
 paul@1136     98 
records test information in subdirectories of `/tmp`.
 
 paul@1136     99 
 
 paul@1102    100 
To run all tests against a different data store, such as a
 
 paul@1102    101 
[[../DatabaseStore|database store]] instead of the [[../FileStore|file store]],
 
 paul@1102    102 
the `STORE_TYPE` environment variable can be specified as in the following
 
 paul@1102    103 
example:
 
 paul@1102    104 
 
 paul@1102    105 
{{{
 
 paul@1102    106 
STORE_TYPE=postgresql ./test_all.sh
 
 paul@1102    107 
}}}
 
 paul@1102    108 
 
 paul@1136    109 
The test suite records `postgresql` tests in a specially-created database
 
 paul@1136    110 
called `imip_agent_test` that the system user running the tests must be allowed
 
 paul@1136    111 
to create and drop. This may require the granting of administrative rights
 
 paul@1136    112 
within PostgreSQL for the system user concerned.
 
 paul@1136    113 
 
 paul@989    114 
Individual tests may also be run directly from the topmost level of the
 
 paul@989    115 
source code distribution. For example:
 
 paul@989    116 
 
 paul@989    117 
{{{
 
 paul@989    118 
tests/test_resource_invitation.sh
 
 paul@989    119 
}}}
 
 paul@989    120 
 
 paul@989    121 
Should everything be functioning correctly, `Success` should be reported
 
 paul@989    122 
repeatedly as opposed to `Failed`. If the latter occurs, the output of the
 
 paul@989    123 
tests should be inspected: a number of files whose names end with `.tmp`
 
 paul@989    124 
will have been saved in the current directory, and these will contain the
 
 paul@989    125 
output from various commands from the last test script invocation; the
 
 paul@989    126 
`err.tmp` will contain tracebacks indicating serious error conditions,
 
 paul@989    127 
should any have occurred.
 
 paul@1102    128 
 
 paul@1102    129 
== Testing in the Deployment Environment ==
 
 paul@1102    130 
 
 paul@1102    131 
Although the above testing may indicate that the software is functional,
 
 paul@1102    132 
it does not demonstrate that the software has been successfully integrated
 
 paul@1102    133 
into the deployment environment. One elementary test involves sending mail
 
 paul@1102    134 
to an address that should be configured to handle incoming calendar messages.
 
 paul@1102    135 
 
 paul@1102    136 
A basic script is provided that replicates a subset of the functionality in
 
 paul@1102    137 
the traditional `mail` command for sending messages. It is invoked by
 
 paul@1102    138 
specifying the sender and recipients of a message and by passing the message
 
 paul@1102    139 
itself to the script's standard input. For example:
 
 paul@1102    140 
 
 paul@1102    141 
{{{
 
 paul@1102    142 
tools/sendmail.py paul.boddie@example.com resource-room-confroom@example.com \
 
 paul@1102    143 
  < tests/templates/event-request.txt
 
 paul@1102    144 
}}}
 
 paul@1102    145 
 
 paul@1102    146 
Here, the sender (`paul.boddie@example.com`) and recipient
 
 paul@1102    147 
(`resource-room-confroom@example.com`) must match the identities specified
 
 paul@1102    148 
within the supplied file (`tests/templates/event-request.txt`), and for a
 
 paul@1102    149 
specific deployment environment these identities will need to be changed.
 
 paul@1102    150 
The following lines from the supplied file would be involved:
 
 paul@1102    151 
 
 paul@1102    152 
{{{
 
 paul@1102    153 
From: paul.boddie@example.com
 
 paul@1102    154 
To: resource-room-confroom@example.com
 
 paul@1102    155 
ORGANIZER:mailto:paul.boddie@example.com
 
 paul@1102    156 
ATTENDEE;ROLE=CHAIR:mailto:paul.boddie@example.com
 
 paul@1102    157 
ATTENDEE;RSVP=TRUE:mailto:resource-room-confroom@example.com
 
 paul@1102    158 
}}}
 
 paul@1102    159 
 
 paul@1102    160 
It makes most sense to choose a recipient acting as a resource so that an
 
 paul@1102    161 
automated response may be generated with the sender receiving this response.
 
 paul@1102    162 
However, other kinds of recipients may also be tested in this way.
 
 paul@1102    163 
 
 paul@1102    164 
The result of this invocation will become known via the following sources of
 
 paul@1102    165 
information:
 
 paul@1102    166 
 
 paul@1102    167 
 * The sender's mailbox (if the recipient sends an automated response)
 
 paul@1102    168 
 * The sender's data store
 
 paul@1102    169 
 * The recipient's mailbox (if the recipient is configured to store mail)
 
 paul@1102    170 
 * The recipient's data store
 
 paul@1102    171 
 * Mail system logs (particularly in case of errors)
 
 paul@1102    172 
 
 paul@1102    173 
See the [[../MailIntegration|mail integration guide]] for more information
 
 paul@1102    174 
about configuring and troubleshooting mail systems.