9. Email Test Servers

In most cases when you write mail receiving or sending applications you will use the "Post Office Protocol" in version 3 (POP3) for receiving emails and the "Simple Mail Transfer Protocol" (SMTP) for sending emails. From a programming point the protocols are very simple. You find an overview description with links to the formal specification on the wikipedia site:

http://en.wikipedia.org/wiki/Post_Office_Protocol
http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

When you write such email handling scripts you will soon find out that it is complicated and time consuming to handle the mail servers correctly. And sending out test emails to real addresses is certainly something that should be avoided.

For this reason Arachno has two build in testing servers that your program can use. They come with a GUI frontend that allows you to specify exactly and reproduceable which mails your program will find in the inbox mail drop and catch all outgoing messages without actually sending them to the given recipients.

On Unix systems we also give you a sendmail compatible wrapper program that you can use if your program does not use the SMTP protocol directly for sending emails.

9.1. Server Configuration

To configure the servers either use "Email Test Server..." from the "Settings" menu or click on the "Email Server" icon in the Arachno settings main window.

The configuration for both email servers are always defined on a project scope. They are saved in the public settings. So you can share the settings across different computers.

The POP3 server configuration has only two essential configuration options: The socket port where the server is listening and some accounts for authentification.

The port number needs a short explaination. We recommend that you do not use a fixed port number. Instead use the fact that whenever Arachno starts a program it defines the ARACHNO_POP3_PORT environment variable and passes the automatically assigned port number as its content. So the code you can use in your program can look like this:

The advantage is that you will never have any conflicts with other servers that already use the same port number and you can open multiple projects that use different email servers withoug further thinking. While you might believe that this is not a problem remember then go back to a project (website or library) you haven't worked on for a few month and you will see that can make your life easier. Of course, you only need to enable the check button and enter a fixed port number if you do want.

With the next check box button you can choose if you want to start the Server automatically when the project is opened. The default is to not start them because only a minorty of projects need them and starting the server has some small influence on the total project startup time and memory consumption.

Simple POP3 servers support two different authentification schemas. The simple one is transmitting unencoded passwords and is just a string comparison on the server side. The second is a more complicated APOP algorithm. Please read the POP3 specification if you want to know more about this. Because a server can only use one of them and is not allowed to switch between the two schemas you have to explicitly enable APOP here if you want use it.

The last option "Disable POP3 logging" is just doing what it says. If you're not interested in looking at the protocol level you can turn this on. The log file is automatically truncated to 0 bytes on each project start, so the logging information will normally not grow to serious sizes even if turned on which is the default.

Finally you have to specify the Name/Password pairs of each account you want to use. You should use special testing passwords and not real ones because the passwords are stored in clear text in the project settings file and readable for everyone that has access to your computer.

The only required SMTP server configuration is the socket port of the server. The setting here is analog to the POP3 server socket port decribed with the difference that the used environment variable is named "ARACHNO_SMTP_PORT".

You can choose if you want to start the Server automatically when the project is opened. This is by default disabled.

The next two settings "Discard all received SMTP messages" and "Disable SMTP logging" have an influence when you intend to run a stress or performance test which sends thousands of emails. In this case the internal handling of the email servers can result in significant memory and cpu usage. If you turn this options on no incoming SMTP data is saved and you will get the highest possible throughput. We tested the implementation on a Dual Core System with 3000 MHz and we recommend that you turn this on if you run tests with more then 1000 email messages in a few seconds.

The SMTP server does not need or support any authentification.

9.2. Email Server Window

Once you configured the server choose the "Email Test Servers" submenu from the "Tools" main menu. In this submenu you can see and change the running status of the two servers. Choosing the "View Servers..." menu command will display the GUI frontend window to the POP3 and SMTP server.

POP3 Email Lists

A POP3 servers do not know anything about folders. They keep all the messages for one account in exactly one list. This is not really good enough when you develop an email processing programs especially when you use fine grained unit test cases. There you want setup a defined environment in which the test case finds only a purchase email in the mailbox. And maybe another test case where the available message is a cancellation email and so on.

This is the reason why you can setup different lists in the Arachno POP3 server and choose which is the active one. Whenever a program connects to the server it will see all the messages in the active list. So every list is holding a different scenario of incomming emails.

The active list manually selected via the listbox in the top of the window. In the next chapter you will see that Arachno comes with a simple function that you can use in your unit testing routines to assure a certain list is active and the messages are available.

There is always a "Default Mailing List" you can rename this list but not delete it. This list exist because there always have to be at least one list. The second mandatory list is called SMTP and it is special in the way that all emails that are send via the SMTP server will be added to this list. You can't delete or reanme the SMTP list. All messages on the SMTP list are removed when you close a project. If you develop an email sending program and leave the project open for a long time it is very wise to clear this list from time to time because every list consumes RAM memory and a little bit CPU time. We recommend to stay below thousand messages per list.

You can create, rename and delete as much additional lists as you want. To do so use the corresponding buttons in the upper part of the window.

Handling Messages in the List

All messages in the list are simple pieces of text. While they should be real messages in RFC-822 email format it can be every piece of text that does not contain a binary 0 bye. So you can add messages to test if your script can handle invalid messages correctly. The format of an email message can be extremely complicated but in the most cases it is just a list of headers with colon separated name value pairs followed by an empty line and the message body. No line can't be longer then 1000 bytes. For example:


To: Jane Doe <jane@example.com>
From: Lothar Scholz <scholz@scriptolutions.com>
Subject: Test Email Message

The message body comes after the separating empty line.

Read more about the email format on the wikipedia site: http://en.wikipedia.org/wiki/MIME.

Arachno does not offer any help for writing an RFC-822 or MIME message. If you want to test your script with a complicated message that contains multiple formats and attachments the simplest way is to create the message with your favorite email program and send the message it to a location from where you can import it via POP3 (see later).
Most email programs also offer a way to view the native unparsed RFC-822 data. In this cases you can simply cut and paste messages.

Next we need to say something about deletion: If your script program issues the command to delete a message the POP3 protocol defines that the message is only to flagged as deleted. It will exist until the connection is closed correctly. In case of an abnormal termination the flag is reset and the message is left in the mail box. Otherwise it is deleted permanently.

Arachno does not allow a POP3 client to really delete any message. This can only be done with via this GUI frontend. So a second state is introduced. If a message is logically deleted from the mailbox by a script you can see a small delete icon in front of this message in the list. You will also see a different icon as soon as the client flags the message for later deletion.

The logically delete markers can be removed from all messages in the current list by hitting the "Reset Delete Marks" button. They are also removed whenever you change the current list. So if you change the list you immediately have restored a new test scenario.

all Operations are locked when a POP3 client script is accessing the mailbox.

Use the eight buttons just below the email list to do all message operations.

Create...: This pops up a dialog where you can add an RFC822 conforming email messsage as plain text. Arachno will automatically handle the line endings correctly.
Edit...: Edit the currently selected message in the list.
Export...: Export all data. This will save all mailing lists except the SMTP list and all the containing messages in one file for a later import operation. You can use this for backup or if you want to clone in a different project.
Import...: Imports the data previously saved with 'Export'. All current mailing lists and messages will be deleted and replaced by the new ones.
Delete: Delete the currently selected message in the list.
Delete All: Delete all messages from the list.
Copy: Copy the content of the currently selected message into the clipboard.
Paste: Paste the clipboard data as a new message into the mailing list. Use Copy/Paste to move messages between different lists.
Reset Delete Marks: This revives the logically deleted message in the list. The next time a new POP3 client connects it will see all the messages again in the mailbox.
Load From POP3: Fills the value of the mailing list by connecting to another POP3 server and loading all messages from there. Use this option to load data from a real email server. You will be asked for all required connection data in a dialog window. If you enter a password here and enable the "Save Password" option your password will be safed in clear text in the project wide settings file. So be carefull with this option.

Finally you can see the two buttons on the bottom of the window. They are used to start and stop the servers. You can also do this from the Tools menu. But this is the only location where you can see on which port numbers the servers are listening for connections if you don't use fixed port numbers.

The two other tabs in this window are file tail watchers to the POP3 and the SMTP logfile. If you want to know what exactly is transmitted you should look here. Keep in mind that there are options to disable the logging in the email server configuration window.

You will see that each message that is received via SMTP has to additional header fields: "X-ARACHNO-SMTP-TO" and "X-ARACHNO-SMTP-FROM". The content of this fields are the email addresses that are used as receiver and transmitter in the SMTP protocol. Normally a SMTP server does not store this information in the transmitted message. You can use them to see if your email implementation handles CC and BCC fields correctly.

9.3. Automated Unit Tests

One of the nicest features is that you can use the SMTP and POP3 server inside your unit tests. The servers are extended by two simple commands that you should use in your setup and teardown unit test method. Sending the "ARACHNO select <name>" command (with a terminating "\r\n" combination) changes the current mailing list for all further operations and resets the deletion mark for all messages on the list. ....TODO code

9.4. Where is the data stored

This section explains some implementation details. It is not guaranteed that the items described here will be the same in the next versions of Arachno.

Every mailing list is represented by a simple textfile that contains the message in unencoded form. But the file does not contain any markers where a message begins or ends. This information is stored in an index file that contains the offset and size of the message and the line that is displayed in the list window. The files are named "email_list_<n>.dat" and "email_list_<n>.idx" where n is a positive number (1=Default Mailing List, 2=SMTP List). The "local_settings.ini" file finally has a section "[Email-Lists]" that gives the right names based on the list number. If you want to copy some data to a differnt project or system you can manually copy the files and then fix the [Email-Lists] section. All files are stored in the local project cache directory.

The same folder also contain the files "email_pop3.log" and "email_smtp.log" which are - as the names suggest - store the logging information from the servers.