Differences between revisions 15 and 99 (spanning 84 versions)
Revision 15 as of 2007-12-01 17:28:46
Size: 8277
Editor: TimoSirainen
Revision 99 as of 2013-09-02 02:01:20
Size: 833
Editor: TimoSirainen
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
imaptest was originally written for stress testing [http://www.dovecot.org/ Dovecot] IMAP server. Its primary testing method is still stress testing, but now it also parses the incoming IMAP replies and complains if anything looks broken. imaptest works with any IMAP server. ImapTest is a generic IMAP server compliancy tester that works with all IMAP servers. It supports:
Line 5: Line 5:
== Compiling ==  * [[ImapTest/TestFeatures|Stress testing with state tracking]]. ImapTest sends random commands to the server and verifies that server's output looks correct.
 * [[ImapTest/ScriptedTests|Scripted testing]] where it runs a list of predefined scripted tests and verifies that server returns expected output.
 * [[Benchmarking]]
Line 7: Line 9:
 1. Download and compile Dovecot v1.1 sources. imaptest uses its library functions.
  1. Get the latest beta from http://dovecot.org/releases/1.1/beta/
  1. Compiling goes the usual way: {{{./configure && make}}} (there's no need for {{{make install}}})
 1. Download http://www.dovecot.org/tools/imaptest.c to Dovecot sources' root directory (i.e. where the {{{configure}}} script exists)
 1. imaptest.c's header comment shows the compile command for gcc, use it or something similar.
== Table of Contents ==
Line 13: Line 11:
You may want to modify the default configuration from #defines at the top of the file. This isn't required, but if you run imaptest often, this way you don't have to give the same parameters every time.

== Running ==

The most important parameters (and their defaults) are:
 * host= Host name/IP address where to connect.
 * port=143: Port what to use.
 * user=tss: Username template. You can use multiple random users and domains by giving %d in the template. So for example {{{user%d}}} returns user1..user100 and {{{user%d@domain%d.org}}} returns user1..100@domain1..100.org. The 1..100 range is hardcoded to the binary. You can change them from {{{USER_RAND}}} and {{{DOMAIN_RAND}}} defines.
 * password=pass: Password to use for all users. There's currently no way to use different passwords for different users.
 * mbox=/home/tss/mail/dovecot-crlf: Path to mbox file where to append messages from. See below for how this is used.

Other useful parameters include:
 * clients=10: Number of simultaneous client connections to use.
 * secs=n: Run imaptest n seconds and then exit.
 * msgs=30: Try to keep the mailbox size around this many messages.
 * box=INBOX: Mailbox to use for testing. INBOX is the default.
 * copybox=n: When testing COPY command, this specifies the destination mailbox.
 * seed=n: Seed to use for random generator. Setting this to some specific value makes repeated benchmarks a bit more reliable, because the used commands should be the same then.
 * disconnect_quit: If a client gets disconnected, quit. Use logout=0 parameter with this one. This is useful when debugging some problem in the server.
 * no_pipelining: Don't send multiple commands at once to server.
 * rawlog: Write rawlog.* files for all connections containing their input and output.

Selecting what to test:
 * <state>=<probability>[,<probability2>]: State probabilities to use. See below.
 * checkpoint=n: Run a checkpoint every n seconds. See below.
 * random: Switch randomly between states.
 * no_tracking: Don't track and complain about IMAP state. Makes it use a bit less CPU.

== Append mbox ==

When saving messages, imaptest needs to get the messages from somewhere. mbox=path parameter specifies path to a file in mbox format that's used. Messages are sequentially appended from there. Once imaptest reaches the last message, it wraps back to appending the first message.

Currently imaptest's state tracking expects that Message-IDs are unique within the mbox, otherwise it gives bogus errors. If you really want to avoid changing the Message-IDs, use no_tracking setting to disable state tracking.

You can get a test mbox file from for example http://dovecot.org/archives/dovecot.mbox. Note that it contains non-unique Message-IDs so you'll have to write some script to change those.

== States ==

States can be specified using full or short names. You specify the probabilities in percents, so for example {{{list=30}}} means that LIST command is executed with 30% probability.

The second probability is mainly useful for APPEND, where it controls how often to append multiple messages with MULTIAPPEND extension, so for example {{{append=80,30}}} means that APPEND command is executed with 80% probability, and after each appended message there's a 30% chance of the APPEND command continuing.

|| Name || Short name || Default% || Description ||
|| AUTHENTICATE || Auth || 0 || Authentication with AUTHENTICATE PLAIN command ||
|| LOGIN || Logi || 100 || Authentication with LOGIN command ||
|| LIST || List || 50 || LIST "" * ||
|| MCREATE || LCre || 0 || CREATE test/x/y mailboxes randomly. '/' separator is hardcoded currently. ||
|| MDELETE || LDel || 0 || DELETE test/x/y mailboxes randomly. ||
|| SELECT || Sele || 100 || SELECT mailbox (required for most states below) ||
|| FETCH || Fetc || 100 || FETCH n:m (UID FLAGS ENVELOPE INTERNALDATE BODYSTRUCTURE) where n:m is a range with random start for 100 messages (or all messages if mailbox has less than 100 messages) ||
|| FETCH2 || Fet2 || 100 || FETCH n (BODY.PEEK[]) where n is a random message ||
|| SEARCH || Sear || 0 || SEARCH BODY hello ||
|| SORT || Sort || 0 || SORT (SUBJECT) US-ASCII for ALL or FLAGGED randomly ||
|| COPY || Copy || 0 || COPY random number of messages ||
|| STORE || Stor || 50 || STORE <random-range> [+-]FLAGS[.SILENT] <random flags and keywords>. Only $Label1..5 are used as keywords. SILENT is used if checkpointing is disabled. \Deleted flags aren't set. ||
|| DELETE || Dele || 100 || STORE <random-range> +FLAGS[.SILENT] \Deleted ||
|| EXPUNGE || Expu || 100 || EXPUNGE ||
|| APPEND || Appe || 100,30 || APPEND messages to mailbox. MULTIAPPEND extension is used if possible. The counter shows number of APPEND commands, so with MULTIAPPEND it doesn't match the actual number of appended messages. ||
|| NOOP || Noop || 0 || NOOP command. ||
|| CHECK || Chec || 0 || CHECK command. ||
|| LOGOUT || Logo || 100 || LOGOUT command. ||
|| DISCONNECT || Disc || 0 || Disconnect without LOGOUT. ||
|| DELAY || Dela || 0 || 1 second delay ||
|| CHECKPOINT! || ChkP || 0 || Use checkpoint parameter to change this. The counter shows number of client connections successfully checkpointed ||

== State tracking ==

imaptest should catch the following errors:

 * Referring to sequences that haven't been announced with EXISTS.
 * Sequence <-> UID map changes unexpectedly
 * Message's metadata changes unexpectedly. Messages are uniquely identified by their Message-ID: header.
  * BODY, BODYSTRUCTURE, ENVELOPE and RFC822.SIZE are currently tracked.
  * IMAP servers handle FETCHes for expunged messages differently. imaptest tries to catch these.
 * FETCH FLAGS listing keywords that haven't been announced with untagged FLAGS.
 * Untagged FLAGS reply dropping a keyword that's still in use.

Checkpointing works by letting all the pending commands finish. Then CHECK command is sent to all sessions. Once they're done, imaptest verifies that all clients' mailbox state looks exactly the same:

 * Number of messages is the same
 * Sequence <-> UID map is the same
 * Flags and keywords are the same
 * \Recent flag for a message exists in only one session (all mailboxes are SELECTed currently)

== Examples ==


./imaptest host= port=143 user=testuser password=testpass mbox=dovecot.mbox

Test IMAP server compliancy by checkpointing every 1 second:

./imaptest checkpoint=1
./imaptest checkpoint=1 logout=0
./imaptest checkpoint=1 rawlog no_pipelining

If you want to do benchmarking, you can set it to run for specified amount of time, and you should also give random number generator the same seed every time:

./imaptest seed=123 secs=300

If you want to test/benchmark only the login+logout speed, use:

./imaptest - select=0

To create a lot of long-running clients doing STATUS and NOOPs:

./imaptest clients=100 - logout=0 status=50 noop=50 delay=100

Benchmarking how fast messages can be saved:

./imaptest - append=100,0 logout=0 msgs=10000000

To test copying messages:

./imaptest copybox=Trash

By default LOGIN command is used. If you want to try AUTHENTICATE PLAIN:

./imaptest auth=100
 * [[ImapTest/Installation|Installation]]
 * [[ImapTest/Running|Running]]
  * [[ImapTest/Examples|Examples]]
 * [[ImapTest/States|States]] that can be used for stress testing
 * [[ImapTest/ScriptedTests|Scripted Testing Configuration]]
 * [[ImapTest/TestFeatures|Supported tests]]
 * [[ImapTest/ServerStatus|IMAP Server Compliancy Status]]

IMAP Server Tester

ImapTest is a generic IMAP server compliancy tester that works with all IMAP servers. It supports:

Table of Contents

None: ImapTest (last edited 2013-09-02 02:01:42 by TimoSirainen)