docs(console): read_until list match + regex

Document that read_until's 'expected' accepts a list (match any) and the
new 'regex' flag, with examples and the bounded-window limitation note.
Regenerated manual PDF.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-14 17:00:46 +02:00
parent e4300ecf7b
commit 3661a71145
2 changed files with 30 additions and 1 deletions

View File

@@ -121,15 +121,44 @@ writeln function is similar to the write function except that a '\n' (newline) c
The ``read_until`` action is waiting for a string pattern from the console,
its parameter are listed below
* ``expected``: Character string to wait for
* ``expected``: the pattern(s) to wait for. It accepts either a **single
value** or a **list of values**; when a list is given the action succeeds
as soon as **any** of the values is seen.
* ``regex``: Boolean value (``True`` or ``False``, default ``False``). When
``True`` every ``expected`` entry is interpreted as a Python regular
expression (searched in the incoming stream, not anchored) instead of a
literal string.
* ``timeout``: Timeout setting for the action (in seconds)
* ``no_fail``: Boolean value (``True`` or ``False``) leading to no error reported
if the expected input is not read
* ``mute``: Boolean value (``True`` or ``False``) does not log any readen data
.. code-block:: yaml
:caption: matching several values, and with a regular expression
# succeeds as soon as one of the three strings is received
- read_until:
expected: [login:, "Password:", "$ "]
timeout: 10
# regex: wait for "version X.Y.Z" with any numbers
- read_until:
expected: 'version \d+\.\d+\.\d+'
regex: True
timeout: 5
The text read by the ``read_until`` action is stored in the global
variable named ``cn_<test_name>`` (See :ref:`global variables<sec_global_variables>`
for more detail on accessing global variables from test items and scripts).
When a list of values is given, the report also records, under the
``matched`` key, which pattern actually matched.
.. note::
``regex`` matching scans a bounded tail of the received stream
(``Console.REGEX_WINDOW`` characters), so a pattern that could only match
after a very large amount of output — or across more than that window —
may not be detected. Literal matching (the default) has no such limit.
In the example above, the global variable ``$(cn_test name in GUI)``
would be created at the end of the step. It would contain the resulting

Binary file not shown.