Merge pull request #3331 from tonybaloney/breakpoint_support

Support for the new builtin breakpoint function in Python 3.7

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index 9b6db82c5..3d5b0536e 100644
--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@@ -189,6 +189,20 @@ in your code and pytest automatically disables its output capture for that test:
   for test output occurring after you exit the interactive PDB_ tracing session
   and continue with the regular test run.
 
+
+.. _`breakpoint-builtin`:
+
+Using the builtin breakpoint function
+-------------------------------------
+
+Python 3.7 introduces a builtin ``breakpoint()`` function. 
+Pytest supports the use of ``breakpoint()`` with the following behaviours:
+
+ - When ``breakpoint()`` is called and ``PYTHONBREAKPOINT`` is set to the default value, pytest will use the custom internal PDB trace UI instead of the system default ``Pdb``.
+ - When tests are complete, the system will default back to the system ``Pdb`` trace UI.
+ - If ``--pdb`` is called on execution of pytest, the custom internal Pdb trace UI is used on ``bothbreakpoint()`` and failed tests/unhandled exceptions.
+ - If ``--pdbcls`` is used, the custom class debugger will be executed when a test fails (as expected within existing behaviour), but also when ``breakpoint()`` is called from within a test, the custom class debugger will be instantiated.
+
 .. _durations:
 
 Profiling test execution duration