98 lines
3.7 KiB
ReStructuredText
98 lines
3.7 KiB
ReStructuredText
.. _sec_parallel_item:
|
|
|
|
**parallel** test item
|
|
============================================================
|
|
|
|
This element is of the following form:
|
|
|
|
.. code-block:: yaml
|
|
:caption: ``parallel`` test item usage example
|
|
|
|
- parallel:
|
|
name: My parallel block
|
|
sync: all
|
|
branches:
|
|
- name: Branch A
|
|
steps:
|
|
- py_func:
|
|
name: Long operation
|
|
file: long_op.py
|
|
func_name: do_work
|
|
- name: Branch B
|
|
wait_for:
|
|
condition: <| "$(ready_flag)" == "True" |>
|
|
timeout: 30
|
|
steps:
|
|
- let:
|
|
name: Mark done
|
|
values:
|
|
- branch_b_done: true
|
|
|
|
The ``parallel`` element runs several sequences of items concurrently. Each
|
|
inner sequence is called a *branch* and runs in its own thread. The parent
|
|
test item waits for branches to finish according to the ``sync`` policy.
|
|
|
|
Attributes
|
|
--------------------
|
|
|
|
* ``branches``: required. A list of branches to execute concurrently. Each
|
|
branch has a ``name`` and a ``steps`` list (same structure as a ``group``
|
|
item). It can also declare a ``wait_for`` precondition (see below).
|
|
* ``sync``: optional, defaults to ``all``.
|
|
|
|
* ``all``: the parallel item completes when *every* branch has finished.
|
|
The result is ``PASS`` if no branch returned ``FAIL`` (skipped or
|
|
disabled branches are ignored, like in ``group``); otherwise ``FAIL``.
|
|
* ``any``: the parallel item completes as soon as the *first* branch
|
|
finishes. The remaining branches are stopped (their next test items
|
|
are not executed). The result is ``PASS`` if at least one branch
|
|
succeeded.
|
|
|
|
* ``no_fail``: optional. When ``true``, a ``FAIL`` result is forced to
|
|
``PASS`` for the parallel item itself (same semantics as for any test
|
|
item). Branches keep their own result.
|
|
|
|
Branch attributes
|
|
--------------------
|
|
|
|
Each entry of ``branches`` is a dict with the following attributes:
|
|
|
|
* ``name``: required. The branch name. Used in reports and as a prefix
|
|
in the live log output (each line printed by the branch is prefixed
|
|
with the branch name in square brackets, e.g. ``[Branch A]``, so
|
|
concurrent branches stay readable).
|
|
* ``steps``: required. The list of test items executed sequentially
|
|
inside the branch.
|
|
* ``wait_for``: optional. Forces the branch to wait until a condition is
|
|
met before running its steps. If the timeout elapses, the branch
|
|
returns ``FAIL`` (the steps are not run). Sub-attributes:
|
|
|
|
* ``condition``: a testium expression evaluated repeatedly (every
|
|
100 ms) until it returns ``True``.
|
|
* ``timeout``: maximum wait, in seconds. Defaults to 30.
|
|
|
|
Reporting
|
|
--------------------
|
|
|
|
Each branch produces its own row in the SQLite report (with type
|
|
``Parallel branch``), in addition to the parent ``Parallel`` row. The
|
|
``log`` column of each row contains only the output emitted from that
|
|
branch's thread, so logs are never mixed between concurrent branches.
|
|
|
|
In the live (terminal / GUI) output, lines emitted from a branch are
|
|
prefixed with the branch name in square brackets (e.g. ``[Branch A]``).
|
|
The prefix is not stored in the SQLite log column.
|
|
|
|
Notes
|
|
--------------------
|
|
|
|
* A ``sleep`` item inside a branch is interruptible: if another
|
|
``sync: any`` branch wins the race, slow ``sleep`` items are aborted
|
|
within ~50 ms.
|
|
* A ``py_func`` or ``console`` item inside a branch is **not**
|
|
interruptible: a ``sync: any`` stop will only take effect after the
|
|
current item returns. The branch will then skip its remaining steps.
|
|
* When a user disables a branch in the GUI tree, the branch returns
|
|
``SKIP`` instantly without affecting the others (it does *not* win a
|
|
``sync: any`` race).
|