bpo-41322: Add unit tests for deprecation of test return values (GH-27846)

Also fix the traceback of warnings.

Doc/library/unittest.rst

@@ -151,6 +151,10 @@ The above examples show the most commonly used :mod:`unittest` features which
 are sufficient to meet many everyday testing needs.  The remainder of the
 documentation explores the full feature set from first principles.
 
+.. versionchanged:: 3.11
+   The behavior of returning a value from a test method (other than the default
+   ``None`` value), is now deprecated.
+
 
 .. _unittest-command-line-interface:
 

Doc/whatsnew/3.11.rst

@@ -395,3 +395,7 @@ Removed
   :func:`~gettext.install` are also removed, since they are only used for
   the ``l*gettext()`` functions.
   (Contributed by Dong-hee Na and Serhiy Storchaka in :issue:`44235`.)
+
+* The behavior of returning a value from a :class:`~unittest.TestCase` and
+  :class:`~unittest.IsolatedAsyncioTestCase` test methods (other than the default ``None``
+  value), is now deprecated.

Lib/unittest/async_case.py

@@ -65,7 +65,7 @@ class IsolatedAsyncioTestCase(TestCase):
     def _callTestMethod(self, method):
         if self._callMaybeAsync(method) is not None:
             warnings.warn(f'It is deprecated to return a value!=None from a '
-                          f'test case ({method})', DeprecationWarning)
+                          f'test case ({method})', DeprecationWarning, stacklevel=4)
 
     def _callTearDown(self):
         self._callAsync(self.asyncTearDown)

Lib/unittest/case.py

@@ -548,7 +548,7 @@ class TestCase(object):
     def _callTestMethod(self, method):
         if method() is not None:
             warnings.warn(f'It is deprecated to return a value!=None from a '
-                          f'test case ({method})', DeprecationWarning)
+                          f'test case ({method})', DeprecationWarning, stacklevel=3)
 
     def _callTearDown(self):
         self.tearDown()

Lib/unittest/test/test_async_case.py

@@ -167,6 +167,26 @@ class TestAsyncCase(unittest.TestCase):
         test.run()
         self.assertEqual(events, ['asyncSetUp', 'test', 'asyncTearDown', 'cleanup'])
 
+    def test_deprecation_of_return_val_from_test(self):
+        # Issue 41322 - deprecate return of value!=None from a test
+        class Test(unittest.IsolatedAsyncioTestCase):
+            async def test1(self):
+                return 1
+            async def test2(self):
+                yield 1
+
+        with self.assertWarns(DeprecationWarning) as w:
+            Test('test1').run()
+        self.assertIn('It is deprecated to return a value!=None', str(w.warnings[0].message))
+        self.assertIn('test1', str(w.warnings[0].message))
+        self.assertEqual(w.warnings[0].filename, __file__)
+
+        with self.assertWarns(DeprecationWarning) as w:
+            Test('test2').run()
+        self.assertIn('It is deprecated to return a value!=None', str(w.warnings[0].message))
+        self.assertIn('test2', str(w.warnings[0].message))
+        self.assertEqual(w.warnings[0].filename, __file__)
+
     def test_cleanups_interleave_order(self):
         events = []
 

Lib/unittest/test/test_case.py

@@ -306,6 +306,26 @@ class Test_TestCase(unittest.TestCase, TestEquality, TestHashing):
 
         Foo('test').run()
 
+    def test_deprecation_of_return_val_from_test(self):
+        # Issue 41322 - deprecate return of value!=None from a test
+        class Foo(unittest.TestCase):
+            def test1(self):
+                return 1
+            def test2(self):
+                yield 1
+
+        with self.assertWarns(DeprecationWarning) as w:
+            Foo('test1').run()
+        self.assertIn('It is deprecated to return a value!=None', str(w.warnings[0].message))
+        self.assertIn('test1', str(w.warnings[0].message))
+        self.assertEqual(w.warnings[0].filename, __file__)
+
+        with self.assertWarns(DeprecationWarning) as w:
+            Foo('test2').run()
+        self.assertIn('It is deprecated to return a value!=None', str(w.warnings[0].message))
+        self.assertIn('test2', str(w.warnings[0].message))
+        self.assertEqual(w.warnings[0].filename, __file__)
+
     def _check_call_order__subtests(self, result, events, expected_events):
         class Foo(Test.LoggingTestCase):
             def test(self):