Skip to main content
Use assert_locator_node to branch your automation based on whether a specific element is present on the page. It evaluates a Playwright locator within a timeout and executes if_nodes if the assertion passes, or else_nodes if it does not. This is the lowest-overhead way to handle optional elements—no LLM call, no extraction variable, just a direct visibility check.

​
Structure

{
  "type": "assert_locator_node",
  "locator": "get_by_role(\"alert\", name=\"Error\")",
  "assertion": "to_be_visible",
  "timeout": 5.0,
  "if_nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_role(\"button\", name=\"Dismiss\")"
        }
      }
    }
  ],
  "else_nodes": []
}

​
Properties

PropertyTypeDefaultDescription
type"assert_locator_node"RequiredNode discriminator
locatorstrRequiredPlaywright locator command (page.<locator> style)
assertion"to_be_visible" | "to_be_hidden"RequiredCondition to test
timeoutfloat5.0Seconds to wait for the assertion before treating it as failed
if_nodeslist[node][]Nodes to run when the assertion passes
else_nodeslist[node][]Nodes to run when the assertion fails (times out)
Both if_nodes and else_nodes accept any node type: action_node, if_else_node, for_loop_node, or nested assert_locator_node.

​
Assertions

AssertionPasses when
to_be_visibleThe element exists in the DOM and is visible within timeout seconds
to_be_hiddenThe element is absent or hidden within timeout seconds
If the assertion does not pass within timeout, else_nodes run (no error is raised).

​
Examples

​
Skip a step when an element is absent

Check whether a “Cookie Consent” banner is visible before trying to dismiss it: 
{
  "type": "assert_locator_node",
  "locator": "get_by_role(\"dialog\", name=\"Cookie Consent\")",
  "assertion": "to_be_visible",
  "timeout": 3.0,
  "if_nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_role(\"button\", name=\"Accept All\")"
        }
      }
    }
  ],
  "else_nodes": []
}

​
Assert an element is hidden before proceeding

Wait up to 10 seconds for a loading spinner to disappear: 
{
  "type": "assert_locator_node",
  "locator": "get_by_test_id(\"loading-spinner\")",
  "assertion": "to_be_hidden",
  "timeout": 10.0,
  "if_nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_role(\"button\", name=\"Submit\")"
        }
      }
    }
  ],
  "else_nodes": [
    {
      "type": "action_node",
      "misc_action": {
        "fail_state": {
          "message": "Loading spinner did not disappear within 10 seconds"
        }
      }
    }
  ]
}

​
Variable substitution in the locator

locator supports {variable[index]} substitution, so you can target elements dynamically: 
{
  "type": "assert_locator_node",
  "locator": "get_by_text(\"{order_id[0]}\")",
  "assertion": "to_be_visible",
  "timeout": 5.0,
  "if_nodes": [ ... ],
  "else_nodes": [ ... ]
}

​
assert_locator_node vs if_else_node

assert_locator_nodeif_else_node
ConditionPlaywright locator visibilityPython expression on a variable
Requires extraction?NoYes — needs an extraction_action with output_variable_names first
CostZero (no LLM)Zero (expression eval) + cost of extraction
Best forElement present/absent checksComparing extracted values, complex logic
Use assert_locator_node when you only need to know if something is on the page. Use if_else_node when you need to compare the content of what was extracted.

​
Locator Syntax

The locator field uses the same Playwright command syntax as interaction actions—omit the leading page.: 
{ "locator": "get_by_role(\"button\", name=\"Submit\")" }
{ "locator": "get_by_label(\"Email\")" }
{ "locator": "get_by_text(\"Order confirmed\")" }
{ "locator": "locator(\"#error-banner\")" }
For full locator syntax guidance see Locators.