Change caplog.get_handler(when) to caplog.get_records(when)

While updating the docs I noticed that caplog.get_handler() exposes
the underlying Handler object, which I think it is a bit too much
detail at this stage. Update to return the records directly instead.

_pytest/logging.py

@@ -144,12 +144,20 @@ def _finalize(self):
     def handler(self):
         return self._item.catch_log_handler
 
-    def get_handler(self, when):
+    def get_records(self, when):
         """
-        Get the handler for a specified state of the tests.
-        Valid values for the when parameter are: 'setup', 'call' and 'teardown'.
+        Get the logging records for one of the possible test phases.
+
+        :param str when:
+            Which test phase to obtain the records from. Valid values are: "setup", "call" and "teardown".
+
+        .. versionadded:: 3.4
         """
-        return self._item.catch_log_handlers.get(when)
+        handler = self._item.catch_log_handlers.get(when)
+        if handler:
+            return handler.records
+        else:
+            return []
 
     @property
     def text(self):

changelog/3117.feature

@@ -1 +1 @@
-New ``caplog.get_handler(when)`` method which provides access to the underlying ``Handler`` class used to capture logging during each testing stage, allowing users to obtain the captured records during ``"setup"`` and ``"teardown"`` stages.
+New ``caplog.get_records(when)`` method which provides access the captured records during each testing stage: ``"setup"``, ``"call"`` and ``"teardown"`` stages.

doc/en/logging.rst

@@ -143,7 +143,21 @@ The ``caplop.records`` attribute contains records from the current stage only, s
 inside the ``setup`` phase it contains only setup logs, same with the ``call`` and
 ``teardown`` phases.
 
-It is possible to access logs from other stages with ``caplog.get_handler('setup').records``.
+To access logs from other stages, use the ``caplog.get_records(when)`` method. As an example,
+if you want to make sure that tests which use a certain fixture never log any warnings, you can inspect
+the records for the ``setup`` and ``call`` stages during teardown like so:
+
+.. code-block:: python
+
+
+    @pytest.fixture
+    def window(caplog):
+        window = create_window()
+        yield window
+        for when in ('setup', 'call'):
+            messages = [x.message for x in caplog.get_records(when) if x.level == logging.WARNING]
+            if messages:
+                pytest.fail('warning messages encountered during testing: {}'.format(messages))
 
 
 caplog fixture API

testing/logging/test_fixture.py

@@ -105,16 +105,16 @@ def logging_during_setup_and_teardown(caplog):
     logger.info('a_setup_log')
     yield
     logger.info('a_teardown_log')
-    assert [x.message for x in caplog.get_handler('teardown').records] == ['a_teardown_log']
+    assert [x.message for x in caplog.get_records('teardown')] == ['a_teardown_log']
 
 
 def test_caplog_captures_for_all_stages(caplog, logging_during_setup_and_teardown):
     assert not caplog.records
-    assert not caplog.get_handler('call').records
+    assert not caplog.get_records('call')
     logger.info('a_call_log')
-    assert [x.message for x in caplog.get_handler('call').records] == ['a_call_log']
+    assert [x.message for x in caplog.get_records('call')] == ['a_call_log']
 
-    assert [x.message for x in caplog.get_handler('setup').records] == ['a_setup_log']
+    assert [x.message for x in caplog.get_records('setup')] == ['a_setup_log']
 
     # This reachers into private API, don't use this type of thing in real tests!
     assert set(caplog._item.catch_log_handlers.keys()) == {'setup', 'call'}