From 7bff6d38c7e6da4d762d155753b3b6fb64fb8e2b Mon Sep 17 00:00:00 2001 From: MShekow Date: Tue, 2 Aug 2016 14:24:09 +0200 Subject: [PATCH 1/3] Added order parameter to 2.0 changelog. Added check_params_cb parameter documentation to waitSignals. Added check_params_cbs and order parameter documentation to waitSignals. #147 --- CHANGELOG.rst | 6 ++-- docs/signals.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 862415af..b399176c 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -39,8 +39,10 @@ New Features is met or a timeout is reached. Useful for testing asynchronous features (like in X window environments for example). -* ``waitSignal`` and ``waitSignals`` can receive an optional callback that can - evaluate if the arguments of emitted signals should resume execution or not. +* ``waitSignal`` and ``waitSignals`` can receive an optional callback (or list of callbacks) + that can evaluate if the arguments of emitted signals should resume execution or not. + Additionally ``waitSignals`` has a new ``order`` parameter that allows to expect signals + and their arguments in a strict, semi-strict or no specific order. Thanks `@MShekow`_ for the PR (`#141`_). * Now which Qt binding ``pytest-qt`` will use can be configured by the ``qt_api`` config option. diff --git a/docs/signals.rst b/docs/signals.rst index 1f5f4a6f..b4939080 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -68,6 +68,31 @@ value of the ``raising`` parameter of the ``qtbot.waitSignal`` and Calls which explicitly pass the ``raising`` parameter are not affected. +check_params_cb parameter +--------------------------------- + +.. versionadded:: 2.0 + +If the signal has parameters you want to compare with expected values, you can pass +``check_params_cb=some_callable(*parameters)`` 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. + +.. code-block:: python + + def test_status_100(status): + """Return true if status has reached 100%.""" + return status == 100 + + def test_status_complete(qtbot): + app = Application() + + # the following raises if the worker's status signal (which has an int parameter) wasn't raised + # with value=100 within the default timeout + with qtbot.waitSignal(app.worker.status, raising=True, check_params_cb=test_status_100) as blocker: + app.worker.start() + + Getting arguments of the emitted signal --------------------------------------- @@ -110,6 +135,65 @@ the ``raising`` parameter:: # signal or a qtbot.SignalTimeoutError will be raised assert_application_results(app) +check_params_cbs parameter +^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 2.0 + +Corresponding to the ``check_params_cb`` parameter of ``waitSignal`` you can use the ``check_params_cbs`` +parameter to check whether one or more of the provided signals are emitted with expected parameters. +Provide a ``list`` of callables, each matching the signature of the corresponding signal +in ``signals`` (just like a slot function would). Like for ``waitSignal``, each callable has to +return ``True`` if parameters match, ``False`` otherwise. +Instead of a specific callable, ``None`` can be provided, to disable parameter checking for the +corresponding signal. +If the number of callbacks doesn't match the number of signals ``ValueError`` will be raised. + +The following example shows that the ``app.worker.status`` signal has to be emitted with values 50 and +100, and the ``app.worker.finished`` signal has to be emitted too (for which no signal parameter +evaluation takes place). + + +.. code-block:: python + + def test_status_100(status): + """Return true if status has reached 100%.""" + return status == 100 + + def test_status_50(status): + """Return true if status has reached 50%.""" + return status == 50 + + def test_status_complete(qtbot): + app = Application() + + signals = [app.worker.status, app.worker.status, app.worker.finished] + callbacks = [test_status_50, test_status_100, None] + with qtbot.waitSignals(signals, raising=True, check_params_cbs=callbacks) as blocker: + app.worker.start() + + +order parameter +^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 2.0 + +By default a test using ``qtbot.waitSignals`` completes successfully if *all* signals in ``signals`` +are emitted, irrespective of their exact order. The ``order`` parameter can be set to ``"strict"`` +to enforce strict signal order. +Exemplary, this means that ``blocker.signal_triggered`` will be ``False`` if ``waitSignals`` expects +the signals ``[a, b]`` but the sender emitted signals ``[a, a, b]``. + +.. note:: + + The tested component can still emit signals unknown to the blocker. E.g. + ``blocker.waitSignals([a, b], raising=True, order="strict")`` won't raise if the signal-sender + emits signals ``[a, c, b]``, as ``c`` is not part of the observed signals. + +A third option is to set ``order="simple"`` which is like "strict", but signals may be emitted +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"``). + Making sure a given signal is not emitted ----------------------------------------- From 474e934c73122fb911d399995171ef4e26f88313 Mon Sep 17 00:00:00 2001 From: MShekow Date: Tue, 2 Aug 2016 15:42:40 +0200 Subject: [PATCH 2/3] Fix underlining in docs. #147 --- docs/signals.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/signals.rst b/docs/signals.rst index b4939080..3eef940f 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -69,7 +69,7 @@ Calls which explicitly pass the ``raising`` parameter are not affected. check_params_cb parameter ---------------------------------- +------------------------- .. versionadded:: 2.0 @@ -136,7 +136,7 @@ the ``raising`` parameter:: assert_application_results(app) check_params_cbs parameter -^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 2.0 From 07c0efeed679cec43cd219c8f93722651c610f98 Mon Sep 17 00:00:00 2001 From: MShekow Date: Tue, 2 Aug 2016 15:45:45 +0200 Subject: [PATCH 3/3] Fixed minor issues in docs. #147 --- docs/signals.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/signals.rst b/docs/signals.rst index 3eef940f..b0294311 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -74,7 +74,7 @@ check_params_cb parameter .. versionadded:: 2.0 If the signal has parameters you want to compare with expected values, you can pass -``check_params_cb=some_callable(*parameters)`` that compares the provided signal parameters to some expected parameters. +``check_params_cb=some_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. @@ -142,7 +142,7 @@ check_params_cbs parameter Corresponding to the ``check_params_cb`` parameter of ``waitSignal`` you can use the ``check_params_cbs`` parameter to check whether one or more of the provided signals are emitted with expected parameters. -Provide a ``list`` of callables, each matching the signature of the corresponding signal +Provide a list of callables, each matching the signature of the corresponding signal in ``signals`` (just like a slot function would). Like for ``waitSignal``, each callable has to return ``True`` if parameters match, ``False`` otherwise. Instead of a specific callable, ``None`` can be provided, to disable parameter checking for the