Update docs

CHANGELOG.md

@@ -2,6 +2,8 @@ v0.4.0 (in development)
 -----------------------
 - Drop support for Python 3.6
 - Support Python 3.11 and 3.12
+- Added `@pytest.mark.fail_slow_setup()` marker and `--fail-slow-setup`
+  command-line option for failing tests whose setups take too long to run
 
 v0.3.0 (2022-08-12)
 -------------------

README.rst

@@ -26,51 +26,109 @@
 | `Issues <https://github.com/jwodder/pytest-fail-slow/issues>`_
 | `Changelog <https://github.com/jwodder/pytest-fail-slow/blob/master/CHANGELOG.md>`_
 
-``pytest-fail-slow`` is a pytest_ plugin for making tests fail that take too
-long to run.  It adds a ``--fail-slow DURATION`` command-line option to pytest
-that causes any & all otherwise-passing tests that run for longer than the
-given duration to be marked as failures, and it adds a
-``@pytest.mark.fail_slow(DURATION)`` marker for making an individual test fail
-if it runs for longer than the given duration.  If ``--fail-slow`` is given and
-a test has the ``@fail_slow()`` marker, the duration given by the marker takes
-precedence for that test.
+``pytest-fail-slow`` is a pytest_ plugin for treating tests as failed if they
+took too long to run.  It adds markers for failing tests if they or their setup
+stages run for longer than a given duration, along with command-line options
+for applying the same cutoff to all tests.
 
 Note that slow tests will still be run to completion; if you want them to
 instead be stopped early, use pytest-timeout_.
 
 .. _pytest: https://docs.pytest.org
 .. _pytest-timeout: https://github.com/pytest-dev/pytest-timeout
 
-A duration can be supplied to the ``--fail-slow`` option as either a bare
-floating-point number of seconds or as a floating-point number followed by one
-of the following units (case insensitive):
 
-- ``h``, ``hour``, ``hours``
-- ``m``, ``min``, ``mins``, ``minute``, ``minutes``
-- ``s``, ``sec``, ``secs``, ``second``, ``seconds``
-- ``ms``, ``milli``, ``millisec``, ``milliseconds``
-- ``us``, ``μs``, ``micro``, ``microsec``, ``microseconds``
+Installation
+============
+``pytest-fail-slow`` requires Python 3.7 or higher and pytest 6.0 or higher.
+Just use `pip <https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to
+install it::
+
+    python3 -m pip install pytest-fail-slow
+
+
+Usage
+=====
+
+Failing Slow Tests
+------------------
+
+To cause a specific test to fail if it takes too long to run, apply the
+``fail_slow`` marker to it, with the desired cutoff time as the argument:
+
+.. code:: python
 
-Durations passed to the ``@pytest.mark.fail_slow()`` marker can be either
-ints/floats (for a number of seconds) or strings in the same format as passed
-to ``--fail-slow``.
+    import pytest
 
-If ``pytest-fail-slow`` marks a test as a failure, the output will include the
-test's duration and the duration threshold, like so::
+    @pytest.mark.fail_slow("5s")
+    def test_something_sluggish():
+        ...
+
+In addition, the ``--fail-slow DURATION`` option can be passed to the
+``pytest`` command to affect all tests in that run.  If ``--fail-slow`` is
+given and a test has the ``fail_slow`` marker, the duration given by the marker
+takes precedence for that test.
+
+If a test fails due to being slow, pytest's output will include the test's
+duration and the duration threshold, like so::
 
     ________________________________ test_func ________________________________
     Test passed but took too long to run: Duration 123.0s > 5.0s
 
-**Note:** Only the durations for tests themselves are taken into consideration.
-If a test passes in less than the specified duration, but one or more fixture
-setups/teardowns take longer than the duration, the test will still be marked
-as passing.
+**Note:** This feature only takes the durations for tests themselves into
+consideration.  If a test passes in less than the specified duration, but one
+or more fixture setups/teardowns take longer than the duration, the test will
+still be marked as passing.  To fail a test if the setup takes too long, see
+below.
 
 
-Installation
-============
-``pytest-fail-slow`` requires Python 3.7 or higher and pytest 6.0 or higher.
-Just use `pip <https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to
-install it::
+Failing Slow Setups
+-------------------
 
-    python3 -m pip install pytest-fail-slow
+*New in version 0.4.0*
+
+To cause a specific test to fail if the setup steps for all of its fixtures
+combined take too long to run, apply the ``fail_slow_setup`` marker to it, with
+the desired cutoff time as the argument:
+
+.. code:: python
+
+    import pytest
+
+    @pytest.mark.fail_slow_setup("5s")
+    def test_costly_resource(slow_to_create):
+        ...
+
+Do not apply the marker to the test's fixtures; markers have no effect on
+fixtures.
+
+In addition, the ``--fail-slow-setup DURATION`` option can be passed to the
+``pytest`` command to affect all tests in that run.  If ``--fail-slow-setup``
+is given and a test has the ``fail_slow_setupresou`` marker, the duration given
+by the marker takes precedence for that test.
+
+If the setup for a test takes too long to run, the test will be marked as
+"errored," the test itself will not be run, and pytest's output will include
+the setup stage's duration and the duration threshold, like so::
+
+    _______________________ ERROR at setup of test_func _______________________
+    Setup passed but took too long to run: Duration 123.0s > 5.0s
+
+**Note:** If a test depends on multiple fixtures and just one of them exceeds
+the given duration on its own, the remaining fixtures will still have their
+setup steps run.  Also, all fixture teardowns will still be run after the test
+would have run.
+
+
+Specifying Durations
+--------------------
+
+A duration passed to a marker or command-line option can be either a bare
+number of seconds or else a floating-point number followed by one of the
+following units (case insensitive):
+
+- ``h``, ``hour``, ``hours``
+- ``m``, ``min``, ``mins``, ``minute``, ``minutes``
+- ``s``, ``sec``, ``secs``, ``second``, ``seconds``
+- ``ms``, ``milli``, ``millisec``, ``milliseconds``
+- ``us``, ``μs``, ``micro``, ``microsec``, ``microseconds``

src/pytest_fail_slow.py

@@ -1,46 +1,17 @@
 """
 Fail tests that take too long to run
 
-``pytest-fail-slow`` is a pytest_ plugin for making tests fail that take too
-long to run.  It adds a ``--fail-slow DURATION`` command-line option to pytest
-that causes any & all otherwise-passing tests that run for longer than the
-given duration to be marked as failures, and it adds a
-``@pytest.mark.fail_slow(DURATION)`` marker for making an individual test fail
-if it runs for longer than the given duration.  If ``--fail-slow`` is given and
-a test has the ``@fail_slow()`` marker, the duration given by the marker takes
-precedence for that test.
+``pytest-fail-slow`` is a pytest_ plugin for treating tests as failed if they
+took too long to run.  It adds markers for failing tests if they or their setup
+stages run for longer than a given duration, along with command-line options
+for applying the same cutoff to all tests.
 
 Note that slow tests will still be run to completion; if you want them to
 instead be stopped early, use pytest-timeout_.
 
 .. _pytest: https://docs.pytest.org
 .. _pytest-timeout: https://github.com/pytest-dev/pytest-timeout
 
-A duration can be supplied to the ``--fail-slow`` option as either a bare
-floating-point number of seconds or as a floating-point number followed by one
-of the following units (case insensitive):
-
-- ``h``, ``hour``, ``hours``
-- ``m``, ``min``, ``mins``, ``minute``, ``minutes``
-- ``s``, ``sec``, ``secs``, ``second``, ``seconds``
-- ``ms``, ``milli``, ``millisec``, ``milliseconds``
-- ``us``, ``μs``, ``micro``, ``microsec``, ``microseconds``
-
-Durations passed to the ``@pytest.mark.fail_slow()`` marker can be either
-ints/floats (for a number of seconds) or strings in the same format as passed
-to ``--fail-slow``.
-
-If ``pytest-fail-slow`` marks a test as a failure, the output will include the
-test's duration and the duration threshold, like so::
-
-    ________________________________ test_func ________________________________
-    Test passed but took too long to run: Duration 123.0s > 5.0s
-
-**Note:** Only the durations for tests themselves are taken into consideration.
-If a test passes in less than the specified duration, but one or more fixture
-setups/teardowns take longer than the duration, the test will still be marked
-as passing.
-
 Visit <https://github.com/jwodder/pytest-fail-slow> for more information.
 """