Merge #17987: properly document support.captured_xxx.

2 files changed, 27 insertions, 9 deletions

diff --git a/Lib/test/support.py b/Lib/test/support.py
index d26e10c..f6f5060 100644
--- a/Lib/test/support.py
+++ b/Lib/test/support.py
@@ -1186,16 +1186,31 @@ def captured_output(stream_name):
 def captured_stdout():
     """Capture the output of sys.stdout:
 
-       with captured_stdout() as s:
+       with captured_stdout() as stdout:
            print("hello")
-       self.assertEqual(s.getvalue(), "hello")
+       self.assertEqual(stdout.getvalue(), "hello\n")
     """
     return captured_output("stdout")
 
 def captured_stderr():
+    """Capture the output of sys.stderr:
+
+       with captured_stderr() as stderr:
+           print("hello", file=sys.stderr)
+       self.assertEqual(stderr.getvalue(), "hello\n")
+    """
     return captured_output("stderr")
 
 def captured_stdin():
+    """Capture the input to sys.stdin:
+
+       with captured_stdin() as stdin:
+           stdin.write('hello\n')
+           stdin.seek(0)
+           # call test code that consumes from sys.stdin
+           captured = input()
+       self.assertEqual(captured, "hello")
+    """
     return captured_output("stdin")
 
 
diff --git a/Lib/test/test_support.py b/Lib/test/test_support.py
index f6ef5f6..340b8da 100644
--- a/Lib/test/test_support.py
+++ b/Lib/test/test_support.py
@@ -130,19 +130,22 @@ class TestSupport(unittest.TestCase):
         self.assertNotIn("bar", sys.path)
 
     def test_captured_stdout(self):
-        with support.captured_stdout() as s:
+        with support.captured_stdout() as stdout:
             print("hello")
-        self.assertEqual(s.getvalue(), "hello\n")
+        self.assertEqual(stdout.getvalue(), "hello\n")
 
     def test_captured_stderr(self):
-        with support.captured_stderr() as s:
+        with support.captured_stderr() as stderr:
             print("hello", file=sys.stderr)
-        self.assertEqual(s.getvalue(), "hello\n")
+        self.assertEqual(stderr.getvalue(), "hello\n")
 
     def test_captured_stdin(self):
-        with support.captured_stdin() as s:
-            print("hello", file=sys.stdin)
-        self.assertEqual(s.getvalue(), "hello\n")
+        with support.captured_stdin() as stdin:
+            stdin.write('hello\n')
+            stdin.seek(0)
+            # call test code that consumes from sys.stdin
+            captured = input()
+        self.assertEqual(captured, "hello")
 
     def test_gc_collect(self):
         support.gc_collect()