Merge pull request #153 from MShekow/master

Support for capturing signals and args and improved SignalTimeoutError messages

Author: nicoddemus

docs/signals.rst

@@ -114,6 +114,16 @@ of the blocker:
 Signals without arguments will set ``args`` to an empty list. If the time out
 is reached instead, ``args`` will be ``None``.
 
+Getting all arguments of non-matching arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.1
+
+When using the ``check_params_cb`` parameter, it may happen that the provided signal is received multiple times with
+different parameter values, which may or may not match the requirements of the callback.
+``all_args`` then contains the list of signal parameters (as tuple) in the order they were received.
+
+
 waitSignals
 -----------
 
@@ -174,7 +184,7 @@ evaluation takes place).
 
 
 order parameter
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^
 
 .. versionadded:: 2.0
 
@@ -194,6 +204,17 @@ A third option is to set ``order="simple"`` which is like "strict", but signals
 in-between the provided ones, e.g. if the expected signals are ``[a, b, c]`` and the sender 
 actually emits ``[a, a, b, a, c]``, the test completes successfully (it would fail with ``order="strict"``).
 
+Getting emitted signals and arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.1
+
+To determine which of the expected signals were emitted during a ``wait()`` you can use
+``blocker.all_signals_and_args`` which contains a list of
+:class:`wait_signal.SignalAndArgs <SignalAndArgs>` objects, indicating the signals (and their arguments)
+in the order they were received.
+
+
 Making sure a given signal is not emitted
 -----------------------------------------
 

pytestqt/qtbot.py

@@ -216,8 +216,12 @@ def waitSignal(self, signal=None, timeout=1000, raising=None, check_params_cb=No
         .. versionadded:: 1.4
            The *raising* parameter.
 
+        .. versionadded:: 2.0
+           The *check_params_cb* parameter.
+
         :param Signal signal:
-            A signal to wait for. Set to ``None`` to just use timeout.
+            A signal to wait for, or a tuple ``(signal, signal_name_as_str)`` to improve the error message that is part
+            of ``SignalTimeoutError``. Set to ``None`` to just use timeout.
         :param int timeout:
             How many milliseconds to wait before resuming control flow.
         :param bool raising:
@@ -226,7 +230,7 @@ def waitSignal(self, signal=None, timeout=1000, raising=None, check_params_cb=No
             This defaults to ``True`` unless ``qt_wait_signal_raising = false``
             is set in the config.
         :param Callable check_params_cb:
-            Optional ``callable(*parameters)`` that compares the provided signal parameters to some expected parameters.
+            Optional ``callable`` that compares the provided signal parameters to some expected parameters.
             It has to match the signature of ``signal`` (just like a slot function would) and return ``True`` if
             parameters match, ``False`` otherwise.
         :returns:
@@ -275,8 +279,9 @@ def waitSignals(self, signals=None, timeout=1000, raising=None, check_params_cbs
            blocker.wait()
 
         :param list signals:
-            A list of :class:`Signal` objects to wait for. Set to ``None`` to just use
-            timeout.
+            A list of :class:`Signal` objects to wait for. Alternatively: a list of (``Signal, str``) tuples of the form
+            ``(signal, signal_name_as_str)`` to improve the error message that is part of ``SignalTimeoutError``.
+            Set to ``None`` to just use timeout.
         :param int timeout:
             How many milliseconds to wait before resuming control flow.
         :param bool raising: