ImapTest Scripted Testing Configuration

The imaptest scripts can be used to test command/response pairs. It's especially helpful for matching untagged replies as responses to commands in a way that should work with all IMAP standards compliant servers. This means that the order of untagged replies isn't important, and for many responses the order of the parameters isn't important.

Test files

Each test consists of one or two files in the test directory:

Messages are appended to the test mailbox from the test.mbox file. If the test-specific mbox file doesn't exist, default.mbox is used instead.

The test file begins with a header, followed by an empty line and then a list of commands.

The header contains "key: value" pairs. Allowed keys are:

For example:

capabilities: CHILDREN LIST-EXTENDED
connections: 2
state: auth

Commands

There are two ways to configure commands:

1)

[<connection #>] OK|NO|BAD|"" <command>
[untagged replies]

2)

[<connection #> <command>
[untagged replies]
OK|NO|BAD|"" [<prefix>]

Connection number is used if the test uses more than one concurrent connection ("connections: n" header). The first way is faster to write, while the second allows matching reply's <prefix>.

For example:

# way 1)
ok select $mailbox
* 0 exists

# way 2)
select $mailbox
* 0 exists
1 ok [read-write]

Untagged replies

Each command can be expected to have zero or more untagged replies. The order of them doesn't matter. The untagged replies can be specified in 3 ways:

For example to make sure LIST is correctly returning "foo/bar", but not "foo":

ok create foo/bar
ok list "" foo/*
* list () "/" foo/bar
! list () "/" foo

Variables

Commands and replies can have $variables. It can also be written as ${variable}. If a variable doesn't have any value yet when it's matched against server input, the variable is initialized from the server input. This allows doing this like:

ok fetch 1,2 uid
* 1 fetch (uid $uid1)
* 2 fetch (uid $uid2)

ok uid store $uid1,$uid2 flags \seen
* 1 fetch (uid $uid1 flags (\seen))
* 2 fetch (uid $uid2 flags (\seen))

If you want to match the imap argument against anything, use "$". This also works for IMAP (lists), unlike named variables. For example:

ok fetch 1 (uid flags)
# flags $ succeeds against any flags-list, while ($) would match any parameter inside the list.
* 1 fetch (uid $ flags $)

Using $n where n is a number maps to sequences at the beginning of a command. These are useful when receiving EXPUNGEs from another session. For example:

1 ok expunge
2 ok uid fetch 3 flags
# server may send expunge before or after fetch - both match this test
* $2 expunge
* $3 fetch (uid 3 (flags ()))

There are also some predefined variables:

Pipelining

Multiple commands can be pipelined, for example:

tag1 status ${mailbox} (messages)
tag2 status ${mailbox}2 (messages)
* status ${mailbox} (messages 0)
* status ${mailbox}2 (messages 0)
tag1 ok
tag2 ok

Directives

$!directives can be used to alter list matching by placing them at the beginning of a list:

If a list has no explicit directives, defaults are used (separately for each list within same command):

NOTE: These defaults within the list aren't used at all if any $! directives are used. For example:

* 1 FETCH (FLAGS ($!extra))

is fully expanded as:

* 1 FETCH ($!unordered=2 FLAGS ($!extra))

So the FLAGS won't have $!unordered or $!ignored=\recent, but the parent FETCH list will have the default $!unordered=2.

Preprocessing

You can use !ifenv, !ifnenv, !else and !endif to run tests only if specified environment variables exist. For example:

!ifenv HAVE_FOO
ok foo
* foo stuff
!endif

The "foo" command is run only have HAVE_FOO environment exists.

Similarly !ifnenv HAVE_FOO block is run only if HAVE_FOO environment doesn't exist.

None: ImapTest/ScriptedTests (last edited 2021-10-13 12:56:39 by TimoSirainen)