@@ -23,16 +23,16 @@ pytest-timeout
2323.. warning ::
2424
2525 Please read this README carefully and only use this plugin if you
26- understand the consequences. This plugin is designed to catch
26+ understand the consequences. This plugin is designed to catch
2727 excessively long test durations like deadlocked or hanging tests,
2828 it is not designed for precise timings or performance regressions.
2929 Remember your test suite should aim to be **fast **, with timeouts
3030 being a last resort, not an expected failure mode.
3131
3232This plugin will time each test and terminate it when it takes too
33- long. Termination may or may not be graceful, please see below, but
33+ long. Termination may or may not be graceful, please see below, but
3434when aborting it will show a stack dump of all thread running at the
35- time. This is useful when running tests under a continuous
35+ time. This is useful when running tests under a continuous
3636integration server or simply if you don't know why the test suite
3737hangs.
3838
@@ -41,15 +41,15 @@ hangs.
4141 While by default on POSIX systems pytest will continue to execute
4242 the tests after a test has timed out this is not always possible.
4343 Often the only sure way to interrupt a hanging test is by
44- terminating the entire process. As this is a hard termination
44+ terminating the entire process. As this is a hard termination
4545 (``os._exit() ``) it will result in no teardown, JUnit XML output
46- etc. But the plugin will ensure you will have the debugging output
46+ etc. But the plugin will ensure you will have the debugging output
4747 on stderr nevertheless, which is the most important part at this
48- stage. See below for detailed information on the timeout methods
48+ stage. See below for detailed information on the timeout methods
4949 and their side-effects.
5050
51- The pytest-timeout plugin has been tested on Python 3.6 and higher,
52- including PyPy3. See tox.ini for currently tested versions.
51+ The pytest-timeout plugin has been tested on Python 3.7 and higher,
52+ including PyPy3. See tox.ini for currently tested versions.
5353
5454
5555Usage
@@ -66,7 +66,7 @@ terminated::
6666 pytest --timeout=300
6767
6868Furthermore you can also use a decorator to set the timeout for an
69- individual test. If combined with the ``--timeout `` flag this will
69+ individual test. If combined with the ``--timeout `` flag this will
7070override the timeout for this individual test:
7171
7272.. code :: python
@@ -76,12 +76,12 @@ override the timeout for this individual test:
7676 pass
7777
7878 By default the plugin will not time out any tests, you must specify a
79- valid timeout for the plugin to interrupt long-running tests. A
79+ valid timeout for the plugin to interrupt long-running tests. A
8080timeout is always specified as a number of seconds, and can be
8181defined in a number of ways, from low to high priority:
8282
83831. You can set a global timeout in the `pytest configuration file `__
84- using the ``timeout `` option. E.g.:
84+ using the ``timeout `` option. E.g.:
8585
8686 .. code :: ini
8787
@@ -115,8 +115,8 @@ Timeout Methods
115115===============
116116
117117Interrupting tests which hang is not always as simple and can be
118- platform dependent. Furthermore some methods of terminating a test
119- might conflict with the code under test itself. The pytest-timeout
118+ platform dependent. Furthermore some methods of terminating a test
119+ might conflict with the code under test itself. The pytest-timeout
120120plugin tries to pick the most suitable method based on your platform,
121121but occasionally you may need to specify a specific timeout method
122122explicitly.
@@ -127,39 +127,39 @@ explicitly.
127127thread
128128------
129129
130- This is the surest and most portable method. It is also the default
131- on systems not supporting the *signal * method. For each test item the
130+ This is the surest and most portable method. It is also the default
131+ on systems not supporting the *signal * method. For each test item the
132132pytest-timeout plugin starts a timer thread which will terminate the
133- whole process after the specified timeout. When a test item finishes
133+ whole process after the specified timeout. When a test item finishes
134134this timer thread is cancelled and the test run continues.
135135
136136The downsides of this method are that there is a relatively large
137137overhead for running each test and that test runs are not completed.
138138This means that other pytest features, like e.g. JUnit XML output or
139- fixture teardown, will not function normally. The second issue might
139+ fixture teardown, will not function normally. The second issue might
140140be alleviated by using the ``--forked `` option of the pytest-forked _
141141plugin.
142142
143143.. _pytest-forked : https://pypi.org/project/pytest-forked/
144144
145- The benefit of this method is that it will always work. Furthermore
145+ The benefit of this method is that it will always work. Furthermore
146146it will still provide you debugging information by printing the stacks
147147of all the threads in the application to stderr.
148148
149149signal
150150------
151151
152152If the system supports the SIGALRM signal the *signal * method will be
153- used by default. This method schedules an alarm when the test item
154- starts and cancels the alarm when the test finishes. If the alarm expires
153+ used by default. This method schedules an alarm when the test item
154+ starts and cancels the alarm when the test finishes. If the alarm expires
155155during the test the signal handler will dump the stack of any other threads
156156running to stderr and use ``pytest.fail() `` to interrupt the test.
157157
158158The benefit of this method is that the pytest process is not
159159terminated and the test run can complete normally.
160160
161161The main issue to look out for with this method is that it may
162- interfere with the code under test. If the code under test uses
162+ interfere with the code under test. If the code under test uses
163163SIGALRM itself things will go wrong and you will have to choose the
164164*thread * method.
165165
@@ -168,9 +168,9 @@ Specifying the Timeout Method
168168
169169The timeout method can be specified by using the ``timeout_method ``
170170option in the `pytest configuration file `__, the ``--timeout_method ``
171- command line parameter or the ``timeout `` marker _. Simply set their
171+ command line parameter or the ``timeout `` marker _. Simply set their
172172value to the string ``thread `` or ``signal `` to override the default
173- method. On a marker this is done using the ``method `` keyword:
173+ method. On a marker this is done using the ``method `` keyword:
174174
175175.. code :: python
176176
@@ -192,7 +192,7 @@ The full signature of the timeout marker is:
192192 pytest.mark.timeout(timeout = 0 , method = DEFAULT_METHOD )
193193
194194 You can use either positional or keyword arguments for both the
195- timeout and the method. Neither needs to be present.
195+ timeout and the method. Neither needs to be present.
196196
197197See the marker api documentation _ and examples _ for the various ways
198198markers can be applied to test items.
@@ -206,12 +206,12 @@ Timeouts in Fixture Teardown
206206============================
207207
208208The plugin will happily terminate timeouts in the finalisers of
209- fixtures. The timeout specified applies to the entire process of
209+ fixtures. The timeout specified applies to the entire process of
210210setting up fixtures, running the tests and finalising the fixtures.
211211However when a timeout occurs in a fixture finaliser and the test
212212suite continues, i.e. the signal method is used, it must be realised
213213that subsequent fixtures which need to be finalised might not have
214- been executed, which could result in a broken test-suite anyway. In
214+ been executed, which could result in a broken test-suite anyway. In
215215case of doubt the thread method which terminates the entire process
216216might result in clearer output.
217217
@@ -221,8 +221,8 @@ Avoiding timeouts in Fixtures
221221The timeout applies to the entire test including any fixtures which
222222may need to be setup or torn down for the test (the exact affected
223223fixtures depends on which scope they are and whether other tests will
224- still use the same fixture). If the timeouts really are too short to
225- include fixture durations, firstly make the timeouts larger ;). If
224+ still use the same fixture). If the timeouts really are too short to
225+ include fixture durations, firstly make the timeouts larger ;). If
226226this really isn't an option a ``timeout_func_only `` boolean setting
227227exists which can be set in the pytest ini configuration file, as
228228documented in ``pytest --help ``.
@@ -243,7 +243,7 @@ Debugger Detection
243243==================
244244
245245This plugin tries to avoid triggering the timeout when a debugger is
246- detected. This is mostly a convenience so you do not need to remember
246+ detected. This is mostly a convenience so you do not need to remember
247247to disable the timeout when interactively debugging.
248248
249249The way this plugin detects whether or not a debugging session is
@@ -260,7 +260,7 @@ variable.
260260Extending pytest-timeout with plugins
261261=====================================
262262
263- ``pytest-timeout `` provides two hooks that can be used for extending the tool. These
263+ ``pytest-timeout `` provides two hooks that can be used for extending the tool. These
264264hooks are used for setting the timeout timer and cancelling it if the timeout is not
265265reached.
266266
@@ -325,7 +325,7 @@ The argument has ``Settings`` namedtuple type with the following fields:
325325----------------
326326
327327When the timeout occurs, user can open the debugger session. In this case, the timeout
328- should be discarded. A custom hook can check this case by calling ``is_debugging() ``
328+ should be discarded. A custom hook can check this case by calling ``is_debugging() ``
329329function:
330330
331331.. code :: python
@@ -344,13 +344,13 @@ function:
344344 Session Timeout
345345===============
346346
347- The above mentioned timeouts are all per test function.
347+ The above mentioned timeouts are all per test function.
348348The "per test function" timeouts will stop an individual test
349- from taking too long. We may also want to limit the time of the entire
349+ from taking too long. We may also want to limit the time of the entire
350350set of tests running in one session. A session all of the tests
351- that will be run with one invokation of pytest.
351+ that will be run with one invocation of pytest.
352352
353- A session timeout is set with `--session-timeout ` and is in seconds.
353+ A session timeout is set with `` --session-timeout ` ` and is in seconds.
354354
355355The following example shows a session timeout of 10 minutes (600 seconds)::
356356
@@ -366,20 +366,20 @@ You can also set the session timeout the pytest configuration file using the ``s
366366 Cooperative timeouts
367367--------------------
368368
369- Session timeouts are cooperative timeouts. pytest-timeout checks the
369+ Session timeouts are cooperative timeouts. pytest-timeout checks the
370370session time at the end of each test function, and stops further tests
371- from running if the session timeout is exceeded. The session will
371+ from running if the session timeout is exceeded. The session will
372372results in a test failure if this occurs.
373373
374374In particular this means if a test does not finish of itself, it will
375- only be interrupted if there is also a function timeout set. A
375+ only be interrupted if there is also a function timeout set. A
376376session timeout is not enough to ensure that a test-suite is
377377guaranteed to finish.
378378
379379Combining session and function timeouts
380380---------------------------------------
381381
382- It works fine to combine both session and function timeouts. In fact
382+ It works fine to combine both session and function timeouts. In fact
383383when using a session timeout it is recommended to also provide a
384384function timeout.
385385
@@ -394,8 +394,9 @@ Changelog
394394
395395x.y.z
396396-----
397-
398- - Detect debuggers registered with sys.monitoring. Thanks Rich
397+ - Add support Python3.13 and Python3.14. Thanks Vladimir
398+ Roshchin.
399+ - Detect debuggers registered with sys.monitoring. Thanks Rich
399400 Chiodo.
400401
4014022.3.1
@@ -408,12 +409,12 @@ x.y.z
408409-----
409410
410411- Fix debugger detection for recent VSCode, this compiles pydevd using
411- cython which is now correctly detected. Thanks Adrian Gielniewski.
412+ cython which is now correctly detected. Thanks Adrian Gielniewski.
412413- Switched to using Pytest's ``TerminalReporter `` instead of writing
413414 directly to ``sys.{stdout,stderr} ``.
414415 This change also switches all output from ``sys.stderr `` to ``sys.stdout ``.
415416 Thanks Pedro Algarvio.
416- - Pytest 7.0.0 is now the minimum supported version. Thanks Pedro Algarvio.
417+ - Pytest 7.0.0 is now the minimum supported version. Thanks Pedro Algarvio.
417418- Add ``--session-timeout `` option and ``session_timeout `` setting.
418419 Thanks Brian Okken.
419420
@@ -444,7 +445,7 @@ x.y.z
4444452.0.0
445446-----
446447
447- - Increase pytest requirement to >=5.0.0. Thanks Dominic Davis-Foster.
448+ - Increase pytest requirement to >=5.0.0. Thanks Dominic Davis-Foster.
448449- Use thread timeout method when plugin is not called from main
449450 thread to avoid crash.
450451- Fix pycharm debugger detection so timeouts are not triggered during
@@ -473,7 +474,7 @@ x.y.z
473474
474475- Give the threads a name to help debugging, thanks Thomas Grainger.
475476- Changed location to https://github.com/pytest-dev/pytest-timeout
476- because bitbucket is dropping mercurial support. Thanks Thomas
477+ because bitbucket is dropping mercurial support. Thanks Thomas
477478 Grainger and Bruno Oliveira.
478479
4794801.3.3
@@ -485,23 +486,23 @@ x.y.z
485486-----
486487
487488- This changelog was omitted for the 1.3.2 release and was added
488- afterwards. Apologies for the confusion.
489- - Fix pytest 3.7.3 compatibility. The capture API had changed
490- slightly and this needed fixing. Thanks Bruno Oliveira for the
489+ afterwards. Apologies for the confusion.
490+ - Fix pytest 3.7.3 compatibility. The capture API had changed
491+ slightly and this needed fixing. Thanks Bruno Oliveira for the
491492 contribution.
492493
4934941.3.1
494495-----
495496
496- - Fix deprecation warning on Python 3.6. Thanks Mickaël Schoentgen
497- - Create a valid tag for the release. Somehow this didn't happen for
497+ - Fix deprecation warning on Python 3.6. Thanks Mickaël Schoentgen
498+ - Create a valid tag for the release. Somehow this didn't happen for
498499 1.3.0, that tag points to a non-existing commit.
499500
5005011.3.0
501502-----
502503
503504- Make it possible to only run the timeout timer on the test function
504- and not the whole fixture setup + test + teardown duration. Thanks
505+ and not the whole fixture setup + test + teardown duration. Thanks
505506 Pedro Algarvio for the work!
506507- Use the new pytest marker API, Thanks Pedro Algarvio for the work!
507508
@@ -511,9 +512,9 @@ x.y.z
511512- Fix for pytest 3.3, thanks Bruno Oliveira.
512513- Update supported python versions:
513514 - Add CPython 3.6.
514- - Drop CPyhon 2.6 (as did pytest 3.3)
515- - Drop CPyhon 3.3
516- - Drop CPyhon 3.4
515+ - Drop CPython 2.6 (as did pytest 3.3)
516+ - Drop CPython 3.3
517+ - Drop CPython 3.4
517518
5185191.2.0
519520-----
@@ -561,7 +562,7 @@ x.y.z
561562* More flexible marker argument parsing: you can now specify the
562563 method using a positional argument.
563564
564- * The plugin is now enabled by default. There is no longer a need to
565+ * The plugin is now enabled by default. There is no longer a need to
565566 specify ``timeout=0 `` in the configuration file or on the command
566567 line simply so that a marker would work.
567568
@@ -576,7 +577,7 @@ x.y.z
576577 ``method `` keyword argument.
577578
578579* Rename the --nosigalrm option to --method=thread to future proof
579- support for eventlet and gevent. Thanks to Ronny Pfannschmidt for
580+ support for eventlet and gevent. Thanks to Ronny Pfannschmidt for
580581 the hint.
581582
582583* Add ``timeout `` and ``timeout_method `` items to the configuration
0 commit comments