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,
|
||||
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.
Reference in New Issue
Block a user