Skip to content

Flow Control

The FlowControl class manages control flow operations including loops, conditions, and data management for test sessions.

Read Data

The read_data method loads tabular data from a file path, an environment variable (using the ENV:VAR_NAME form), or a 2D list; applies optional query parts such as select=col1,col2 and filter expressions; and stores the result in the session's elements. For full details on the ENV: prefix, query syntax (including variable resolution ${var}), and all supported file_path forms, see Read Data in Keyword Usage.

optics_framework.api.flow_control.FlowControl

Manages control flow operations (loops, conditions, data) for a session.

condition(*args)

Evaluates conditions and executes corresponding targets.

Parameters:

Name Type Description Default
args str

Condition-target pairs, optionally ending with an else target: "cond1", "target1", "cond2", "target2", [else_target]. A condition is a module name (prefix ! to invert) or an expression.

 ()

Returns:

Type Description
Optional[List[Any]]

Result of the matched target module, or None if nothing matched.

date_evaluate(param1, param2, param3, param4='%d %B')

Evaluates a date expression based on an input date and stores the result in session.elements.

Parameters:

Name Type Description Default
param1 str

The variable name (placeholder) where the evaluated date result will be stored.

 required
param2 str

The input date string (e.g., "04/25/2025" or "2025-04-25"). Format is auto-detected.

 required
param3 str

The date expression to evaluate, such as "+1 day", "-2 days", or "today".

 required
param4 Optional[str]

The output format for the evaluated date (default is "%d %B", e.g., "26 April").

 '%d %B'

Returns:

Type Description
str

The resulting evaluated and formatted date string.

Raises:

Type Description
OpticsError

If the session is not present, the input date format cannot be detected, or the expression format is invalid.

Example:

date_evaluate("tomorrow", "04/25/2025", "+1 day")
-> Stores "26 April" in session.elements["tomorrow"]

evaluate(param1, param2)

Evaluates an expression and stores the result in session.elements.

Parameters:

Name Type Description Default
param1 str

Variable name to store the result under, e.g. ${result}.

 required
param2 str

Expression to evaluate; ${var} refs are substituted first, then run through a restricted eval (arithmetic, comparisons, ternary).

 required

Returns:

Type Description
Any

The evaluated result (also stored as a string in session.elements).

execute_module(module_name)

Executes a module's keywords using the session's keyword_map.

Not exposed on the Optics SDK — session.modules is only populated by CSV/YAML-driven execution; SDK/Robot Framework users should call keywords directly or write a real function/keyword instead.

Parameters:

Name Type Description Default
module_name str

The module to execute.

 required

Returns:

Type Description
List[Any]

Results of each keyword call in the module, in order.

invoke_api(api_identifier)

Invokes an API call based on a definition from the session's API data.

Parameters:

Name Type Description Default
api_identifier str

API to call, in collection.api_name form.

 required

Returns:

Type Description
dict[str, Any]

status_code, headers, body and elapsed_ms of the response.

read_data(input_element, file_path, query='')

Reads tabular data from a CSV file, JSON file, environment variable, or a 2D list, applies optional filtering and column selection, and stores the result in the session's elements.

Parameters:

Name Type Description Default
input_element str

Variable name where the result is stored (e.g. ${data}). Prefer ${name} form.

 required
file_path Union[str, List[Any]]

Data source. One of: (1) path to a .csv or .json file; (2) string ENV:VAR_NAME to use an environment variable (value parsed as JSON, CSV, or plain string); (3) a 2D list with first row as headers (Python API only).

 required
query str

Optional semicolon-separated parts: select=col1,col2 and/or filter expressions (pandas-style). Any ${varname} in the query is resolved from session.elements before evaluation. Default "".

 ''

Returns:

Type Description
List[Any]

The stored value as a list (or list of lists for multi-row results). Also writes into session.elements under the name derived from input_element.

run_loop(target, *args)

Runs a loop over a target module, either by count or with variables.

Parameters:

Name Type Description Default
target str

The module name to execute in the loop.

 required
args str

A single count (e.g. "5"), or variable-iterable pairs (e.g. "${user}", "a|b|c") to iterate one value per run.

 ()

Returns:

Type Description
List[Any]

One result list per iteration.