fix documentation and test of getoutput

it returns both stdout and stderr
closes gh-3280

IPython/utils/_process_common.py

@@ -103,9 +103,7 b' def process_handler(cmd, callback, stderr=subprocess.PIPE):'
 
 
 def getoutput(cmd):
-    """Return standard output of executing cmd in a shell.
-
-    Accepts the same arguments as os.system().
+    """Run a command and return its stdout/stderr as a string.
 
     Parameters
     ----------
@@ -114,9 +112,12 b' def getoutput(cmd):'
 
     Returns
     -------
-    stdout : str
+    output : str
+      A string containing the combination of stdout and stderr from the
+    subprocess, in whatever order the subprocess originally wrote to its
+    file descriptors (so the order of the information in this string is the
+    correct order as would be seen if running the command in a terminal).
     """
-
     out = process_handler(cmd, lambda p: p.communicate()[0], subprocess.STDOUT)
     if out is None:
         return ''

IPython/utils/tests/test_process.py

@@ -111,7 +111,11 b' class SubProcessTestCase(TestCase, tt.TempFileMixin):'
 
     def test_getoutput(self):
         out = getoutput('python "%s"' % self.fname)
-        self.assertEqual(out, 'on stdout')
+        # we can't rely on the order the line buffered streams are flushed
+        try:
+            self.assertEqual(out, 'on stderron stdout')
+        except AssertionError:
+            self.assertEqual(out, 'on stdouton stderr')
 
     def test_getoutput_quoted(self):
         out = getoutput('python -c "print (1)"')
@@ -125,7 +129,7 b' class SubProcessTestCase(TestCase, tt.TempFileMixin):'
         out = getoutput("python -c 'print (\"1\")'")
         self.assertEqual(out.strip(), '1')
 
-    def test_getoutput(self):
+    def test_getoutput_error(self):
         out, err = getoutputerror('python "%s"' % self.fname)
         self.assertEqual(out, 'on stdout')
         self.assertEqual(err, 'on stderr')