@@ -361,93 +361,147 @@ def pytest_make_parametrize_id(
361
361
362
362
363
363
# -------------------------------------------------------------------------
364
- # generic runtest related hooks
364
+ # runtest related hooks
365
365
# -------------------------------------------------------------------------
366
366
367
367
368
368
@hookspec (firstresult = True )
369
369
def pytest_runtestloop (session : "Session" ) -> Optional [object ]:
370
- """ called for performing the main runtest loop
371
- (after collection finished).
370
+ """Performs the main runtest loop (after collection finished).
372
371
373
- Stops at first non-None result, see :ref:`firstresult`
372
+ The default hook implementation performs the runtest protocol for all items
373
+ collected in the session (``session.items``), unless the collection failed
374
+ or the ``collectonly`` pytest option is set.
374
375
375
- :param _pytest.main.Session session: the pytest session object
376
+ If at any point :py:func:`pytest.exit` is called, the loop is
377
+ terminated immediately.
378
+
379
+ If at any point ``session.shouldfail`` or ``session.shouldstop`` are set, the
380
+ loop is terminated after the runtest protocol for the current item is finished.
381
+
382
+ :param _pytest.main.Session session: The pytest session object.
383
+
384
+ Stops at first non-None result, see :ref:`firstresult`.
385
+ The return value is not used, but only stops further processing.
376
386
"""
377
387
378
388
379
389
@hookspec (firstresult = True )
380
390
def pytest_runtest_protocol (
381
391
item : "Item" , nextitem : "Optional[Item]"
382
392
) -> Optional [object ]:
383
- """ implements the runtest_setup/call/teardown protocol for
384
- the given test item, including capturing exceptions and calling
385
- reporting hooks.
393
+ """Performs the runtest protocol for a single test item.
386
394
387
- :arg item: test item for which the runtest protocol is performed.
395
+ The default runtest protocol is this (see individual hooks for full details):
388
396
389
- :arg nextitem: the scheduled-to-be-next test item (or None if this
390
- is the end my friend). This argument is passed on to
391
- :py:func:`pytest_runtest_teardown`.
397
+ - ``pytest_runtest_logstart(nodeid, location)``
392
398
393
- :return boolean: True if no further hook implementations should be invoked.
399
+ - Setup phase:
400
+ - ``call = pytest_runtest_setup(item)`` (wrapped in ``CallInfo(when="setup")``)
401
+ - ``report = pytest_runtest_makereport(item, call)``
402
+ - ``pytest_runtest_logreport(report)``
403
+ - ``pytest_exception_interact(call, report)`` if an interactive exception occurred
394
404
405
+ - Call phase, if the the setup passed and the ``setuponly`` pytest option is not set:
406
+ - ``call = pytest_runtest_call(item)`` (wrapped in ``CallInfo(when="call")``)
407
+ - ``report = pytest_runtest_makereport(item, call)``
408
+ - ``pytest_runtest_logreport(report)``
409
+ - ``pytest_exception_interact(call, report)`` if an interactive exception occurred
395
410
396
- Stops at first non-None result, see :ref:`firstresult` """
411
+ - Teardown phase:
412
+ - ``call = pytest_runtest_teardown(item, nextitem)`` (wrapped in ``CallInfo(when="teardown")``)
413
+ - ``report = pytest_runtest_makereport(item, call)``
414
+ - ``pytest_runtest_logreport(report)``
415
+ - ``pytest_exception_interact(call, report)`` if an interactive exception occurred
397
416
417
+ - ``pytest_runtest_logfinish(nodeid, location)``
398
418
399
- def pytest_runtest_logstart (nodeid , location ):
400
- """ signal the start of running a single test item.
419
+ :arg item: Test item for which the runtest protocol is performed.
401
420
402
- This hook will be called **before** :func:`pytest_runtest_setup`, :func:`pytest_runtest_call` and
403
- :func:`pytest_runtest_teardown` hooks.
421
+ :arg nextitem: The scheduled-to-be-next test item (or None if this is the end my friend).
404
422
405
- :param str nodeid: full id of the item
406
- :param location: a triple of ``(filename, linenum, testname)``
423
+ Stops at first non-None result, see :ref:`firstresult`.
424
+ The return value is not used, but only stops further processing.
407
425
"""
408
426
409
427
410
- def pytest_runtest_logfinish (nodeid , location ):
411
- """ signal the complete finish of running a single test item.
428
+ def pytest_runtest_logstart (
429
+ nodeid : str , location : Tuple [str , Optional [int ], str ]
430
+ ) -> None :
431
+ """Called at the start of running the runtest protocol for a single item.
412
432
413
- This hook will be called **after** :func:`pytest_runtest_setup`, :func:`pytest_runtest_call` and
414
- :func:`pytest_runtest_teardown` hooks.
433
+ See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
415
434
416
- :param str nodeid: full id of the item
417
- :param location: a triple of ``(filename, linenum, testname)``
435
+ :param str nodeid: Full node ID of the item.
436
+ :param location: A triple of ``(filename, lineno, testname)``.
437
+ """
438
+
439
+
440
+ def pytest_runtest_logfinish (
441
+ nodeid : str , location : Tuple [str , Optional [int ], str ]
442
+ ) -> None :
443
+ """Called at the end of running the runtest protocol for a single item.
444
+
445
+ See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
446
+
447
+ :param str nodeid: Full node ID of the item.
448
+ :param location: A triple of ``(filename, lineno, testname)``.
418
449
"""
419
450
420
451
421
452
def pytest_runtest_setup (item : "Item" ) -> None :
422
- """ called before ``pytest_runtest_call(item)``. """
453
+ """Called to perform the setup phase for a test item.
454
+
455
+ The default implementation runs ``setup()`` on ``item`` and all of its
456
+ parents (which haven't been setup yet). This includes obtaining the
457
+ values of fixtures required by the item (which haven't been obtained
458
+ yet).
459
+ """
423
460
424
461
425
462
def pytest_runtest_call (item : "Item" ) -> None :
426
- """ called to execute the test ``item``. """
463
+ """Called to run the test for test item (the call phase).
464
+
465
+ The default implementation calls ``item.runtest()``.
466
+ """
427
467
428
468
429
469
def pytest_runtest_teardown (item : "Item" , nextitem : "Optional[Item]" ) -> None :
430
- """ called after ``pytest_runtest_call`` .
470
+ """Called to perform the teardown phase for a test item .
431
471
432
- :arg nextitem: the scheduled-to-be-next test item (None if no further
472
+ The default implementation runs the finalizers and calls ``teardown()``
473
+ on ``item`` and all of its parents (which need to be torn down). This
474
+ includes running the teardown phase of fixtures required by the item (if
475
+ they go out of scope).
476
+
477
+ :arg nextitem: The scheduled-to-be-next test item (None if no further
433
478
test item is scheduled). This argument can be used to
434
479
perform exact teardowns, i.e. calling just enough finalizers
435
480
so that nextitem only needs to call setup-functions.
436
481
"""
437
482
438
483
439
484
@hookspec (firstresult = True )
440
- def pytest_runtest_makereport (item : "Item" , call : "CallInfo[None]" ) -> Optional [object ]:
441
- """ return a :py:class:`_pytest.runner.TestReport` object
442
- for the given :py:class:`pytest.Item <_pytest.main.Item>` and
443
- :py:class:`_pytest.runner.CallInfo`.
485
+ def pytest_runtest_makereport (
486
+ item : "Item" , call : "CallInfo[None]"
487
+ ) -> Optional ["TestReport" ]:
488
+ """Called to create a :py:class:`_pytest.reports.TestReport` for each of
489
+ the setup, call and teardown runtest phases of a test item.
444
490
445
- Stops at first non-None result, see :ref:`firstresult` """
491
+ See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
492
+
493
+ :param CallInfo[None] call: The ``CallInfo`` for the phase.
494
+
495
+ Stops at first non-None result, see :ref:`firstresult`.
496
+ """
446
497
447
498
448
499
def pytest_runtest_logreport (report : "TestReport" ) -> None :
449
- """ process a test setup/call/teardown report relating to
450
- the respective phase of executing a test. """
500
+ """Process the :py:class:`_pytest.reports.TestReport` produced for each
501
+ of the setup, call and teardown runtest phases of an item.
502
+
503
+ See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
504
+ """
451
505
452
506
453
507
@hookspec (firstresult = True )
@@ -779,11 +833,17 @@ def pytest_keyboard_interrupt(
779
833
def pytest_exception_interact (
780
834
node : "Node" , call : "CallInfo[object]" , report : "Union[CollectReport, TestReport]"
781
835
) -> None :
782
- """called when an exception was raised which can potentially be
836
+ """Called when an exception was raised which can potentially be
783
837
interactively handled.
784
838
785
- This hook is only called if an exception was raised
786
- that is not an internal exception like ``skip.Exception``.
839
+ May be called during collection (see :py:func:`pytest_make_collect_report`),
840
+ in which case ``report`` is a :py:class:`_pytest.reports.CollectReport`.
841
+
842
+ May be called during runtest of an item (see :py:func:`pytest_runtest_protocol`),
843
+ in which case ``report`` is a :py:class:`_pytest.reports.TestReport`.
844
+
845
+ This hook is not called if the exception that was raised is an internal
846
+ exception like ``skip.Exception``.
787
847
"""
788
848
789
849
0 commit comments