Docs: suggest direct methods instead of qtbot's

Updates the documentation to use direct methods in most interactions,
as the documentation currently leads users to call `qtbot`'s methods
for normal interactions, such changing the text of a `QLineEdit` or an
item of a `QComboBox`.

Also changed some code examples to use `.. code-block: python`, so they
are formatted by black.

Co-authored-by: Florian Bruhin <[email protected]>

Author: nicoddemus

docs/intro.rst

@@ -6,8 +6,7 @@ pytest-qt is a `pytest`_ plugin that allows programmers to write tests
 for `PyQt5`_, `PyQt6`_, `PySide2`_ and `PySide6`_ applications.
 
 The main usage is to use the ``qtbot`` fixture, responsible for handling ``qApp``
-creation as needed and provides methods to simulate user interaction,
-like key presses and mouse clicks:
+creation as needed, and registering widgets for testing:
 
 
 .. code-block:: python
@@ -16,8 +15,8 @@ like key presses and mouse clicks:
         widget = HelloWidget()
         qtbot.addWidget(widget)
 
-        # click in the Greet button and make sure it updates the appropriate label
-        qtbot.mouseClick(widget.button_greet, QtCore.Qt.LeftButton)
+        # Click the greet button and make sure the appropriate label is updated.
+        widget.button_greet.click()
 
         assert widget.greet_label.text() == "Hello!"
 

docs/note_dialogs.rst

@@ -49,12 +49,14 @@ And now it is also easy to mock ``AskNameAndAgeDialog.ask`` when testing the for
 .. code-block:: python
 
     def test_form_registration(qtbot, monkeypatch):
-        form = RegistrationForm()
+        user = User.empty_user()
+        form = RegistrationForm(user)
 
         monkeypatch.setattr(
-            AskNameAndAgeDialog, "ask", classmethod(lambda *args: ("Jonh", 30))
+            AskNameAndAgeDialog, "ask", classmethod(lambda *args: ("John", 30))
         )
-        qtbot.click(form.enter_info())
-        # calls AskNameAndAgeDialog.ask
-        # test that the rest of the form correctly behaves as if
-        # user entered "Jonh" and 30 as name and age
+        # Clicking on the button will call AskNameAndAgeDialog.ask in its slot.
+        form.enter_info_button.click()
+
+        assert user.name == "John"
+        assert user.age == 30

docs/qapplication.rst

@@ -26,7 +26,7 @@ For example:
         exit_calls = []
         monkeypatch.setattr(QApplication, "exit", lambda: exit_calls.append(1))
         button = get_app_exit_button()
-        qtbot.click(button)
+        button.click()
         assert exit_calls == [1]
 
 
@@ -37,7 +37,7 @@ Or using the ``mock`` package:
     def test_exit_button(qtbot):
         with mock.patch.object(QApplication, "exit"):
             button = get_app_exit_button()
-            qtbot.click(button)
+            button.click()
             assert QApplication.exit.call_count == 1
 
 

docs/tutorial.rst

@@ -18,25 +18,29 @@ to search for and a button to browse for the desired directory. Its source code
 
 .. _here: https://github.com/nicoddemus/PySide-Examples/blob/master/examples/dialogs/findfiles.py
 
-To test this widget's basic functionality, create a test function::
+To test this widget's basic functionality, create a test function:
 
-    def test_basic_search(qtbot, tmpdir):
-        '''
+.. code-block:: python
+
+    def test_basic_search(qtbot, tmp_path):
+        """
         test to ensure basic find files functionality is working.
-        '''
-        tmpdir.join('video1.avi').ensure()
-        tmpdir.join('video1.srt').ensure()
+        """
+        tmp_path.joinpath("video1.avi").touch()
+        tmp_path.joinpath("video1.srt").touch()
 
-        tmpdir.join('video2.avi').ensure()
-        tmpdir.join('video2.srt').ensure()
+        tmp_path.joinpath("video2.avi").touch()
+        tmp_path.joinpath("video2.srt").touch()
 
 Here the first parameter indicates that we will be using a ``qtbot`` fixture to control our widget.
 The other parameter is pytest's standard tmpdir_ that we use to create some files that will be
 used during our test.
 
 .. _tmpdir: http://pytest.org/latest/tmpdir.html
 
-Now we create the widget to test and register it::
+Now we create the widget to test and register it:
+
+.. code-block:: python
 
     window = Window()
     window.show()
@@ -45,24 +49,50 @@ Now we create the widget to test and register it::
 .. tip:: Registering widgets is not required, but recommended because it will ensure those widgets get
     properly closed after each test is done.
 
-Now we use ``qtbot`` methods to simulate user interaction with the dialog::
+Now we can interact with the widgets directly:
+
+.. code-block:: python
 
     window.fileComboBox.clear()
-    qtbot.keyClicks(window.fileComboBox, '*.avi')
+    window.fileComboBox.setCurrentText("*.avi")
 
     window.directoryComboBox.clear()
-    qtbot.keyClicks(window.directoryComboBox, str(tmpdir))
+    window.directoryComboBox.setCurrentText(str(tmp_path))
+
+
+We use the ``QComboBox.setCurrentText`` method to change the current item selected in the combo box.
+
+
+.. _note-about-qtbot-methods:
 
-The method ``keyClicks`` is used to enter text in the editable combo box, selecting the desired mask
-and directory.
+.. note::
 
-We then simulate a user clicking the button with the ``mouseClick`` method::
+    In general, prefer to use a widget's own methods to interact with it: ``QComboBox.setCurrentIndex``, ``QLineEdit.setText``,
+    etc. Those methods will emit the appropriate signal, so the test will work just the same as if the user themselves
+    have interacted with the controls.
 
-    qtbot.mouseClick(window.findButton, QtCore.Qt.LeftButton)
+    Note that ``qtbot`` provides a number of methods to simulate actual interaction, for example ``keyClicks``, ``mouseClick``,
+    etc. Those methods should be used only in specialized situations, for example if you are creating a custom drawing widget
+    and want to simulate actual clicks.
+
+    For normal interactions, always prefer widget methods (``setCurrentIndex``, ``setText``, etc) -- ``qtbot``'s methods
+    (``keyClicks``, ``mouseClick``, etc) will trigger an actual event, which will then need to be processed in the next
+    pass of the event loop, making the test unreliable and flaky. Also some operations are hard to simulate using
+    raw clicks, for example selecting an item on a ``QComboBox``, which will need two ``mouseClick``
+    calls to simulate properly, while figuring out where to click.
+
+
+We then simulate a user clicking the button:
+
+.. code-block:: python
+
+    window.findButton.click()
 
 Once this is done, we inspect the results widget to ensure that it contains the expected files we
-created earlier::
+created earlier:
+
+.. code-block:: python
 
     assert window.filesTable.rowCount() == 2
-    assert window.filesTable.item(0, 0).text() == 'video1.avi'
-    assert window.filesTable.item(1, 0).text() == 'video2.avi'
+    assert window.filesTable.item(0, 0).text() == "video1.avi"
+    assert window.filesTable.item(1, 0).text() == "video2.avi"

docs/virtual_methods.rst

@@ -7,13 +7,14 @@ It is common in Qt programming to override virtual C++ methods to customize
 behavior, like listening for mouse events, implement drawing routines, etc.
 
 Fortunately, all Python bindings for Qt support overriding these virtual methods
-naturally in your Python code::
+naturally in your Python code:
 
-    class MyWidget(QWidget):
+.. code-block:: python
 
+    class MyWidget(QWidget):
         # mouseReleaseEvent
         def mouseReleaseEvent(self, ev):
-            print('mouse released at: %s' % ev.pos())
+            print(f"mouse released at: {ev.pos()}")
 
 In ``PyQt5`` and ``PyQt6``, exceptions in virtual methods will by default call
 abort(), which will crash the interpreter. All other Qt wrappers will print the
@@ -22,12 +23,14 @@ value is required).
 
 This might be surprising for Python users which are used to exceptions
 being raised at the calling point: For example, the following code will just
-print a stack trace without raising any exception::
+print a stack trace without raising any exception:
 
-    class MyWidget(QWidget):
+.. code-block:: python
 
+    class MyWidget(QWidget):
         def mouseReleaseEvent(self, ev):
-            raise RuntimeError('unexpected error')
+            raise RuntimeError("unexpected error")
+
 
     w = MyWidget()
     QTest.mouseClick(w, QtCore.Qt.LeftButton)
@@ -49,7 +52,9 @@ Disabling the automatic exception hook
 --------------------------------------
 
 You can disable the automatic exception hook on individual tests by using a
-``qt_no_exception_capture`` marker::
+``qt_no_exception_capture`` marker:
+
+.. code-block:: python
 
     @pytest.mark.qt_no_exception_capture
     def test_buttons(qtbot):

src/pytestqt/qtbot.py

@@ -55,6 +55,13 @@ class QtBot:
     Those methods are just forwarded directly to the `QTest API`_. Consult the documentation for more
     information.
 
+    .. note::
+        These methods should be rarely be used, in general prefer to interact with widgets
+        using their own methods such as ``QComboBox.setCurrentText``, ``QLineEdit.setText``, etc.
+        Doing so will have the same effect as users interacting with the widget, but are more reliable.
+
+        See :ref:`this note in the tutorial <note-about-qtbot-methods>` for more information.
+
     ---
 
     Below are methods used to simulate sending key events to widgets: