---------------------
SMTP Client Test Plan
---------------------
-Ian! D. Allen - idallen@idallen.ca

I recommend using a shell script test_plan.sh to create an automated
test plan; so, you don't have to redo all the tests manually every time
you change something in your client.

To test SMTP responses, you can "fake" a whole set of responses from
an SMTP server by putting the lines you want the fake server to send
in a text file and using "nc" as the server:

   $ nc -v -l localhost 55555 <file       # Red Hat systems
   $ nc -v -l -p 55555 localhost <file    # Debian systems

If you start the above fake SMTP server and then connect your SMTP
client to port 55555, it will read lines from the given file used as
input to "nc", allowing you to test your client against a variety of
SMTP server responses.  (You can also just type the lines in by hand.)

#!/bin/sh -u
# This script runs tests on an SMTP client in the current directory.
# It creates a fake SMTP server using "nc" that feeds SMTP response
# lines back to the client.  No mail is actually sent.
#
# The script waits for RETURN after every test, if stdin is a terminal.
# (To run tests without prompting, redirect stdin from /dev/null )
#
# This only runs tests of the client connecting to "localhost".
# Some other test should verify that the client can connect to other hosts.
#
# If your machine is loaded down, you may find that lines sent from
# client to server don't appear on the screen right after they are
# sent; they collect together and appear after the client exits.
# You can try adding a small wait ("-i 1") to the server to let the
# output lines appear more interleaved with the client input.
#
# - Ian! D. Allen idallen@idallen.ca

# set standard shell PATH and file creation mask
#
PATH=/bin:/usr/bin ; export PATH
umask 022

CLIENT=./smtpclient.pl            # name of client executable
PORT=55555                        # an unused fake SMTP server port

# The correct command line used to run the test SMTP client:
#
RUNTEST=" $CLIENT -to user@domain.com -from sender@domain.com -smtpserver localhost -port $PORT "

# The command line used to run the fake SMTP server:
# (You may find adding "-i 1" makes output interleave better.)
#
if [ -e /etc/redhat-release -o -e /etc/mandriva-release ] ; then
    RUNSERVER=" nc -l localhost $PORT "     # Red Hat Linux
else
    RUNSERVER=" nc -l -p $PORT localhost "  # Debian/Ubuntu
fi

# Global variable used to count each test
#
testno=0

# A temp file used to build SMTP responses from the fake SMTP server:
# A temp file used as the message being sent (input to the client):
#
smtp=/tmp/$USER.smtp.$$
rm -f $smtp
message=/tmp/$USER.message.$$
rm -f $message

# Remove the tmp files on exit or SIGHUP or SIGINT interrupt.
# Also kill any left over "nc" processes run by this $USER.
#
trap " rm -f $smtp $message; killall -u $USER -q nc; exit " 0 1 2

# The message below tests to make sure leading periods are escaped:
#
cat <<EOF >$message
Subject: This is a test message

Body Line 1.
.Line starting with a period.
Body Line 3.
.
Body Line 5.
EOF

# This is how we actually run a test.
# - connect to and flush any existing left-over server (make it exit)
# - start a fake server in background, reading from the SMTP response file
#   - number the output of the server to make it easy to see
# - run the client against the server
# - possibly pause and ask to run the next test
# - kill the server in case it didn't exit
#
DoTest () {
    echo " "
    echo "=============================================================="
    echo "Test $testno: $*"
    echo "=============================================================="

    # Connect to and flush any existing left-over server (make it exit).
    #
    nc -w 1 -v localhost $PORT </dev/null >/dev/null 2>&1

    # Start our fake SMTP server in the background:
    #  - use cat to make unprintable chars visible and number the output
    # Make sure the server started (kill -0).
    #
    $RUNSERVER <$smtp | cat -v -n &
    if ! kill -0 $! ; then
	echo 1>&2 "$0: Unable to start $RUNSERVER"
	exit 1
    fi
    echo " "

    # Run our client, with message, against the server.
    #
    $RUNTEST <$message
    echo "*** Client exit status is $?"
    echo " "

    # If stdin is a terminal, prompt to continue next test.
    # (To run tests without prompting, redirect stdin from /dev/null )
    #
    if [ -t 0 ] ; then
	let next=testno+1
    	echo 1>&2 "$0: Press RETURN to go to next test (#$next)..."
	read junk
    else
	# Sleep a bit to give the fake server time to exit on its own.
    	sleep 1
    fi

    kill $! 2>/dev/null  # kill any left-over background nc server
}

##########################################################################
# This test is for a plain SMTP session with a few continuation lines.
#
let testno=testno+1
cat <<EOF >$smtp
220 test$testno greeting
250-test$testno response to EHLO
250-test$testno option1
250-test$testno option2
250-test$testno option3
250 test$testno optionlast
250 test$testno response to MAIL FROM
250 test$testno response to RCPT TO
354 test$testno response to DATA
250 test$testno response to end of DATA
221 test$testno response to QUIT (closing)
EOF

DoTest "A few continuation lines"

##########################################################################
# This tests a small message length.
#
let testno=testno+1
cat <<EOF >$smtp
220 test$testno greeting
250-test$testno response to EHLO
250 SIZE 50
250 test$testno response to MAIL FROM
250 test$testno response to RCPT TO
354 test$testno response to DATA
250 test$testno response to end of DATA
221 test$testno response to QUIT (closing)
EOF

DoTest "A fixed small message length"

##########################################################################
# This tests a refused greeting.
#
let testno=testno+1
cat <<EOF >$smtp
554 test$testno refused greeting
EOF

DoTest "A refused greeting"


##########################################################################
# This tests an error refused EHLO.
#
let testno=testno+1
cat <<EOF >$smtp
220 test$testno greeting
504 test$testno error refused EHLO
EOF

DoTest "An error refused EHLO - exit status EX_UNAVAILABLE (69)"

##########################################################################
# This tests a temporary refused EHLO.
#
let testno=testno+1
cat <<EOF >$smtp
220 test$testno greeting
421 test$testno temporary refused EHLO
EOF

DoTest "A temporary refused EHLO - exit status EX_TEMPFAIL (75)"

##########################################################################
# This tests a line too short.
#
let testno=testno+1
cat <<EOF >$smtp
xx
EOF

DoTest "A line too short."

##########################################################################
# This tests a time-out.  (Make sure the client has small time-outs!)
#
let testno=testno+1
cat <<EOF >$smtp
220 test$testno greeting
EOF

DoTest "A time-out"

##########################################################################
# more tests here ...