Clarify e-mail settings and testing. Closes kiwitcms#1070

docs/source/configuration.rst

@@ -57,23 +57,46 @@ Your server/docker container clock should also match the accurate time of day!
     navigation bar! All other timestamps are in the same time zone!
 
 
-Using Amazon SES instead of SMTP email
---------------------------------------
-
+E-mail settings
+---------------
 Kiwi TCMS supports email notifications which by default are sent over SMTP and
-need to be configured via the following settings::
+need to be configured via the following settings:
 
-    # standard Django settings
-    EMAIL_HOST = 'smtp.example.com'
-    EMAIL_PORT = 25
-    DEFAULT_FROM_EMAIL = '[email protected]'
+- Common settings::
 
+    DEFAULT_FROM_EMAIL = '[email protected]'
     # additional Kiwi TCMS setting
     EMAIL_SUBJECT_PREFIX = '[Kiwi-TCMS] '
 
-If you'd like to use an external email service, like Amazon SES you also need
-to configure the following settings::
+- SMTP specific settings::
+
+    EMAIL_HOST = 'smtp.example.com'
+    EMAIL_PORT = 25
+    EMAIL_HOST_USER = 'smtp_username'
+    EMAIL_HOST_PASSWORD = 'smtp_password'
+
+To enable SSL or TLS support include one of the following::
+
+    EMAIL_USE_TLS = True
+    EMAIL_USE_SSL = True
+
+For more details refer to Django documentation at https://docs.djangoproject.com/en/3.0/topics/email/
+
+
+Testing and debugging e-mail configuration
+------------------------------------------
+Sending test e-mail to one or more addresses::
+
+    docker exec -it kiwi_web /Kiwi/manage.py sendtestemail [email protected] [email protected] ...
+
+More details at: https://docs.djangoproject.com/en/3.0/ref/django-admin/#sendtestemail
+
+
+Using Amazon SES instead of SMTP email
+--------------------------------------
 
+If you'd like to use an external email service, like Amazon SES you need
+to configure the following settings instead::
 
     EMAIL_BACKEND = 'django_ses.SESBackend'
     AWS_SES_ACCESS_KEY_ID = 'xxxxxxxxxxxxxxxxxxxx'

tcms/core/tests/test_sendtestemail.py

@@ -0,0 +1,13 @@
+from django.core.management import call_command
+from django.test import TestCase, override_settings
+import socket
+
+
+class TestSendTestEmail(TestCase):
+    """Test manage.py sendtestemail command"""
+
+    @override_settings(EMAIL_HOST='bogus.nonexistent')
+    def test_send_false_server(self):
+        """test command with fake SMTP server"""
+        call_command('sendtestemail', '--admins')
+        self.assertRaises(socket.gaierror)

tcms/settings/common.py

@@ -51,10 +51,17 @@
 # Email settings
 # DEFAULT_FROM_EMAIL must be defined if you want Kiwi TCMS to send emails.
 # You also need to configure the email backend. For more information see:
-# https://docs.djangoproject.com/en/2.0/topics/email/#quick-example
+# https://docs.djangoproject.com/en/3.0/topics/email/
 DEFAULT_FROM_EMAIL = '[email protected]'
+SERVER_EMAIL = DEFAULT_FROM_EMAIL
 EMAIL_SUBJECT_PREFIX = '[Kiwi-TCMS] '
 
+#  SMTP specific settings
+#  EMAIL_HOST = 'smtp.example.com'
+#  EMAIL_PORT = 25
+#  EMAIL_HOST_USER = 'smtp_username'
+#  EMAIL_HOST_PASSWORD = 'smtp_password'
+
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # ~~ You may want to override the following settings as well