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:
@@ -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,
|
The ``read_until`` action is waiting for a string pattern from the console,
|
||||||
its parameter are listed below
|
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)
|
* ``timeout``: Timeout setting for the action (in seconds)
|
||||||
* ``no_fail``: Boolean value (``True`` or ``False``) leading to no error reported
|
* ``no_fail``: Boolean value (``True`` or ``False``) leading to no error reported
|
||||||
if the expected input is not read
|
if the expected input is not read
|
||||||
* ``mute``: Boolean value (``True`` or ``False``) does not log any readen data
|
* ``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
|
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>`
|
variable named ``cn_<test_name>`` (See :ref:`global variables<sec_global_variables>`
|
||||||
for more detail on accessing global variables from test items and scripts).
|
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)``
|
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
|
would be created at the end of the step. It would contain the resulting
|
||||||
|
|||||||
Binary file not shown.
Reference in New Issue
Block a user