python · brianmay · May 1, 2017 · May 1, 2017 · May 1, 2017 · May 1, 2017
diff --git a/Lib/unittest/case.py b/Lib/unittest/case.py
@@ -5,6 +5,7 @@
 import difflib
 import logging
 import pprint
+import pydoc
 import re
 import warnings
 import collections
@@ -338,6 +339,25 @@ def __exit__(self, exc_type, exc_value, tb):
                 .format(logging.getLevelName(self.level), self.logger.name))
 
 
+def short_description_from_docstring(text):
+    """
+    Return the test case short description from a docstring.
+
+    Ths docstring is parsed by the standard `pydoc.splitdoc` function
+    into (`synopsis`, `long_description`).
+
+    If there is no `synopsis`, return None.
+    """
+    if text:
+        (synopsis, long_description) = pydoc.splitdoc(text)
+        synopsis = synopsis.strip()
+    else:
+        # The text is either an empty string, or some other false value.
+        synopsis = None
+
+    return synopsis
+
+
 class TestCase(object):
     """A class whose instances are single test cases.
 
@@ -463,15 +483,8 @@ def defaultTestResult(self):
         return result.TestResult()
 
     def shortDescription(self):
-        """Returns a one-line description of the test, or None if no
-        description has been provided.
-
-        The default implementation of this method returns the first line of
-        the specified test method's docstring.
-        """
-        doc = self._testMethodDoc
-        return doc and doc.split("\n")[0].strip() or None
-
+        """ Return a one-line description of the test, if any; otherwise None. """
+        return short_description_from_docstring(self._testMethodDoc)
 
     def id(self):
         return "%s.%s" % (strclass(self.__class__), self._testMethodName)
@@ -1395,8 +1408,7 @@ def __repr__(self):
     def shortDescription(self):
         if self._description is not None:
             return self._description
-        doc = self._testFunc.__doc__
-        return doc and doc.split("\n")[0].strip() or None
+        return short_description_from_docstring(self._testFunc.__doc__)
 
 
 class _SubTest(TestCase):

diff --git a/Lib/unittest/test/test_case.py b/Lib/unittest/test/test_case.py
@@ -596,6 +596,48 @@ def testShortDescriptionWithMultiLineDocstring(self):
                  'Tests shortDescription() for a method with a longer '
                  'docstring.')
 
+    @unittest.skipIf(
+        sys.flags.optimize >= 2,
+        "Docstrings are omitted with -O2 and above")
+    def testShortDescriptionWithSurroundingSpaceOneLineDocstring(self):
+        """ Surrounding space should be stripped to get the shortDescription. """
+        expected_description = (
+            "Surrounding space should be stripped"
+            " to get the shortDescription.")
+        self.assertEqual(self.shortDescription(), expected_description)
+
+    @unittest.skipIf(
+        sys.flags.optimize >= 2,
+        "Docstrings are omitted with -O2 and above")
+    def testShortDescriptionWithSurroundingNewlineOneLineDocstring(self):
+        """
+        Surrounding newlines should be stripped to get the shortDescription.
+        """
+        expected_description = (
+            "Surrounding newlines should be stripped"
+            " to get the shortDescription.")
+        self.assertEqual(self.shortDescription(), expected_description)
+
+    @unittest.skipIf(
+        sys.flags.optimize >= 2,
+        "Docstrings are omitted with -O2 and above")
+    def testShortDescriptionWithSurroundingNewlineMultiLineDocstring(self):
+        """
+        Surrounding newlines should be stripped to get the shortDescription.
+
+        The specification of how docstring space should be parsed is at
+        https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
+        which requires that “Blank lines should be removed from the
+        beginning and end of the docstring.”
+
+        The PEP 257 algorithm is implemented by `pydoc.splitdoc`.
+
+        """
+        expected_description = (
+            "Surrounding newlines should be stripped"
+            " to get the shortDescription.")
+        self.assertEqual(self.shortDescription(), expected_description)
+
     def testAddTypeEqualityFunc(self):
         class SadSnake(object):
             """Dummy class for test_addTypeEqualityFunc."""

diff --git a/Lib/unittest/test/test_functiontestcase.py b/Lib/unittest/test/test_functiontestcase.py
@@ -126,23 +126,65 @@ def test_id(self):
 
         self.assertIsInstance(test.id(), str)
 
-    # "Returns a one-line description of the test, or None if no description
-    # has been provided. The default implementation of this method returns
-    # the first line of the test method's docstring, if available, or None."
-    def test_shortDescription__no_docstring(self):
+    def test_shortDescription__no_description_no_docstring(self):
+        """ Should return None by default for shortDescription. """
         test = unittest.FunctionTestCase(lambda: None)
 
         self.assertEqual(test.shortDescription(), None)
 
-    # "Returns a one-line description of the test, or None if no description
-    # has been provided. The default implementation of this method returns
-    # the first line of the test method's docstring, if available, or None."
-    def test_shortDescription__singleline_docstring(self):
+    def test_shortDescription__singleline_description(self):
+        """ Should use the specified description for shortDescription. """
         desc = "this tests foo"
         test = unittest.FunctionTestCase(lambda: None, description=desc)
 
         self.assertEqual(test.shortDescription(), "this tests foo")
 
+    def test_shortDescription__no_description_singleline_docstring(self):
+        """ Should use the function docstring for the shortDescription. """
+        test_function = (lambda: None)
+        test_function.__doc__ = """Should use the function docstring."""
+        test = unittest.FunctionTestCase(test_function)
+        expected_description = "Should use the function docstring."
+        self.assertEqual(test.shortDescription(), expected_description)
+
+    def test_shortDescription__singleline_docstring_space_surrounded(self):
+        """ Surrounding space should be stripped to get the shortDescription. """
+        test_function = (lambda: None)
+        test_function.__doc__ = """ Surrounding space should be stripped. """
+        test = unittest.FunctionTestCase(test_function)
+        expected_description = "Surrounding space should be stripped."
+        self.assertEqual(test.shortDescription(), expected_description)
+
+    def test_shortDescription__singleline_docstring_newline_surrounded(self):
+        """
+        Surrounding newlines should be stripped to get the shortDescription.
+        """
+        test_function = (lambda: None)
+        test_function.__doc__ = """
+            Surrounding newlines should be stripped.
+            """
+        test = unittest.FunctionTestCase(test_function)
+        expected_description = "Surrounding newlines should be stripped."
+        self.assertEqual(test.shortDescription(), expected_description)
+
+    def test_shortDescription__multiline_docstring_newline_surrounded(self):
+        """
+        Surrounding newlines should be stripped to get the shortDescription.
+        """
+        test_function = (lambda: None)
+        test_function.__doc__ = """
+            Surrounding newlines should be stripped.
+
+            The specification of how docstring space should be parsed is at
+            https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
+            which requires that “Blank lines should be removed from the
+            beginning and end of the docstring.”
+
+            """
+        test = unittest.FunctionTestCase(test_function)
+        expected_description = "Surrounding newlines should be stripped."
+        self.assertEqual(test.shortDescription(), expected_description)
+
 
 if __name__ == "__main__":
     unittest.main()