describe session timeout better

README.rst

@@ -344,9 +344,15 @@ function:
 Session Timeout
 ===============
 
-The above mentioned timeouts are all per test function. You can also set a
-session timeout in seconds. The following example shows a session timeout
-of 10 minutes (600 seconds)::
+The above mentioned timeouts are all per test function. 
+The "per test function" timeouts will stop an individual test
+from taking too long. We may also want to limit the time of the entire 
+set of tests running in one session. A session all of the tests
+that will be run with one invokation of pytest.
+
+A session timeout is set with `--session-timeout` and is in seconds.
+
+The following example shows a session timeout of 10 minutes (600 seconds)::
 
    pytest --session-timeout=600
 
@@ -357,14 +363,14 @@ You can also set the session timeout the pytest configuration file using the ``s
       [pytest]
       session_timeout = 600
 
-Friendly timeouts
+Cooperative timeouts
 -----------------
 
-Session timeouts are "friendly" timeouts. The plugin checks the session time at the end of
+Session timeouts are cooperative timeouts. The plugin checks the session time at the end of
 each test function, and stops further tests from running if the session timeout is exceeded.
 
-Combining session and function
-------------------------------
+Combining session and function timeouts
+---------------------------------------
 
 It works fine to combine both session and function timeouts.
 For example, to limit test functions to 5 seconds and the full session to 100 seconds::

test_pytest_timeout.py

@@ -611,12 +611,9 @@ def test_foo():
 
 
 def test_session_timeout(pytester):
-    # 2 tests, each with 0.5 sec timeouts
-    # each using a fixture with 0.5 sec setup and 0.5 sec teardown
-    # So about 1.5 seconds per test, ~3 sec total,
-    # Therefore:
-    # A timeout of 1.25 sec should happen during the teardown of the first test
-    # and the second test should NOT be run
+    # This is designed to timeout during hte first test to ensure 
+    # - the first test still runs to completion
+    # - the second test is not started 
     pytester.makepyfile(
         """
         import time, pytest
@@ -636,7 +633,8 @@ def test_two(slow_setup_and_teardown):
     )
     result = pytester.runpytest_subprocess("--session-timeout", "2")
     result.stdout.fnmatch_lines(["*!! session-timeout: 2.0 sec exceeded !!!*"])
-    result.assert_outcomes(passed=1)
+    # This would be 2 passed if the second test was allowed to run
+    result.assert_outcomes(passed=1)  
 
 
 def test_ini_session_timeout(pytester):