assertWithAI

Use AI to verify complex UI states with natural language assertions.

Experimental, needs an AI tool

This command uses an AI model, so it needs an AI command-line tool (Claude Code, OpenAI Codex, or Gemini CLI) set up in Settings → Intelligence. See AI test analysis and the AI assistant. The AI can answer differently between runs.

The assertWithAI command checks the screen against a natural language assertion. Astra Scout captures the screen and its element list, sends them with your assertion to the AI provider you chose, and gets back a true or false answer with a reason.

Use it when an element-based assertion such as assertVisible cannot express the check, for example a visual pattern or a two-factor authentication prompt.

Syntax

- assertWithAI: "The screen has a Sign in button"

You can also use the expanded syntax:

- assertWithAI:
    assertion: A two-factor authentication prompt, with space for 6 digits, is visible.
    optional: false

Parameters

Parameter	Type	Description
assertion	string	Required. The natural language description of the expected screen state.
optional	boolean	Optional. When true, a failed assertion is shown in red but the flow continues. Default true.
timeout	number	Optional. Maximum time to wait for the AI, in milliseconds. Default 60000.

TIP

optional is true by default so that an unreliable AI answer does not break a run. Set optional: false to stop the flow when the assertion is false.

How Astra Scout runs it

• The step sends one AI request with the screenshot (when the provider accepts images) and the list of UI elements. It costs one model call.
• Choose the provider and model in Settings → Intelligence → Defaults → AI commands in flows.
• The result panel of the step records the verdict, the assertion, the raw answer, the model and the screenshot path.
• If the AI reports a confidence below 0.6, the verdict of the run is Unsure, not Passed.
• Text on the screen is sent as untrusted data. The prompt tells the AI to ignore any instruction the screen shows.
• After a step types a secret (for example inputText: ${PASSWORD}), later AI steps send no screenshot until the app is reopened. See No screenshots after typing a secret.

Related commands

• assertNoDefectsWithAI
• extractTextWithAI
• assertVisible