Repository files navigation

⚠Not intended for use with production systems. ⚠

This fixture is intended to address cases where to test an application that sends an email, it needs to be intercepted for subsequent processing. For example, sending an email with a code for password reset or two-factor authentication. This fixture allows a test to trigger the email being sent, ensure that it's sent, and read the email.

To install using pip, first upgrade pip to the latest version to avoid any issues installingcryptography:

python -m pip install --upgrade pippip install pytest-smtpd

Or, if you're using setuptools, it can be included in theextras_require argument of asetup.py file:

setup(    ...extras_require={"test": ["pytest","pytest-smtpd",        ],    },)

and then installed with pip (-e assumes that you want your project to be editable):

python -m pip install --upgrade pippip install -e .[test]

TheSMTPDFix plugin,smtpd, automatically registers for use with pytest when you install smtpdfix. To use it simply add to your test method.

fromsmtplibimportSMTPdeftest_sendmail(smtpd):from_addr="from.addr@example.org"to_addrs="to.addr@example.org"msg= (f"From:{from_addr}\r\n"f"To:{to_addrs}\r\n"f"Subject: Foo\r\n\r\n"f"Foo bar")withSMTP(smtpd.hostname,smtpd.port)asclient:client.sendmail(from_addr,to_addrs,msg)assertlen(smtpd.messages)==1

To use STARTTLS:

fromsmtplibimportSMTPdeftest_sendmail(smtpd):smptd.config.use_starttls=Truefrom_="from.addr@example.org"to_="to.addr@example.org"msg= (f"From:{from_}\r\n"f"To:{to_}\r\n"f"Subject: Foo\r\n\r\n"f"Foo bar")withSMTP(smtpd.hostname,smtpd.port)asclient:client.starttls()# Note that you need to call starttls first.client.sendmail(from_addr,to_addrs,msg)assertlen(smtpd.messages)==1

To use TLS encryption on the connections:

fromsmtplibimportSTMP_SSL# Note the different client class.deftest_custom_certificate(smtpd):smtpd.config.use_ssl=Truefrom_="from.addr@example.org"to_="to.addr@example.org"msg= (f"From:{from_}\r\n"f"To:{to_}\r\n"f"Subject: Foo\r\n\r\n"f"Foo bar")withSMTP_SSL(smtpd.hostname,smtpd.port)asclient:client.sendmail(from_addr,to_addrs,msg)assertlen(smtpd.messages)==1

The certificates included with the fixture will work for addresses localhost, localhost.localdomain, 127.0.0.1, 0.0.0.1, ::1. If using other addresses the key (key.pem) and certificate (cert.pem) must be in a location specified underSMTP_SSL_CERTS_PATH.

Configuration is handled through properties in theconfig of the fixture and are initially set from environment variables:

Many libraries for sending email have built-in methods for testing and using these methods should generally be prefered over pytest-smtpd. Some known solutions:

• fastapi-mail: has arecord_messsages() method to intercept the mail. Instructions on how to suppress the sending of mail and implement it can be seen athttps://sabuhish.github.io/fastapi-mail/example/#unittests-using-fastapimail
• flask-mail: has a method to suppress sending and capture the email for testing purposes.Instructions

To develop and test smtpdfix you will need to installpytest-asyncio to run asynchronous tests,isort to sort imports andflake8 to lint. To install in a virtual environment for development:

python -m venv venv./venv/scripts/activatepip install -e .[dev]

Code is tested using tox:

tox

Quick tests can be handled by running pytest directly:

pytest

• Firewalls may interfere with the operation of the smtp server.
• Authenticating with LOGIN and PLAIN mechanisms fails over TLS/SSL, but works with STARTTLS.smtpdfix Issue #10
• Currently no support for termination through signals.smtpdfix Issue #4

Written with ☕ and ❤ in Montreal, QC