Interactive Exploration
When you ask the agent to create a QA plan, it often needs to discover page structure, find reliable selectors, and understand how the application behaves. The agent uses exploration sessions to do this autonomously — opening a browser, navigating through the application one action at a time, and inspecting the results before moving on.
How It Works
Section titled “How It Works”When the agent determines that it needs to investigate the application before building a plan, it automatically starts an exploration session. Within a session, the agent executes actions one at a time and receives immediate feedback (DOM HTML, screenshots, URLs) after each action. This lets the agent identify selectors, verify navigation flows, and adapt to unexpected UI states — all without any manual intervention.
Exploration vs. run_scenario:
| Exploration | run_scenario | |
|---|---|---|
| Browser lifetime | Kept alive across actions | Created and destroyed per run |
| Feedback | After each individual action | After the full scenario completes |
| Results recorded | No (local logs only) | No |
| Use case | Investigating before planning | Testing a complete scenario |
What the Agent Does
Section titled “What the Agent Does”Starting a session
Section titled “Starting a session”The agent calls start_exploration to create a session. The browser is not launched until the first browser action, so session creation is instant.
| Parameter | Description |
|---|---|
env_name | Environment name to load from .aqua/environments/<name>.json. |
environment | Variable overrides (highest priority). |
qa_plan_id | QA Plan ID to pull default variables from. |
viewport | Viewport preset: pc (1280×720, default) or mobile (375×667). |
Sessions automatically expire after 15 minutes of inactivity. The timer resets on each action.
Executing actions
Section titled “Executing actions”The agent calls explore_action to execute actions within the session. Each call accepts exactly one of the following action types:
browser_step— Execute a single browser action (navigate, click, type, etc.) and receive the resulting page DOM, screenshot, URL, and title.browser_steps— Execute multiple browser actions in sequence. Only the final page state is returned. Useful for replaying a known sequence quickly.http_request— Send an HTTP request and receive the status code, headers, body, and duration.browser_assertion— Evaluate an assertion against the current page state without modifying it.
The agent can also extract values from HTTP responses using JSONPath and store them as session variables for use in subsequent actions.
After each action, the agent analyzes the feedback to decide what to do next — for example, identifying which selector to use for a button, or confirming that a navigation succeeded before proceeding.
Ending a session
Section titled “Ending a session”Once the agent has gathered enough information, it calls end_exploration to clean up resources (browser process, memory). If the agent forgets or the session is interrupted, it automatically expires after 15 minutes of inactivity.
Example
Section titled “Example”When you ask the agent to create a QA plan, the agent autonomously explores the application to gather the information it needs.
Your prompt:
Create a QA plan for the login flow and the profile editing page against the local environment.
What the agent does behind the scenes:
- Starts an exploration session against the local environment.
- Navigates to the login page and examines the DOM to find the email and password input selectors.
- Fills in test credentials and clicks the login button.
- Observes the resulting page to confirm the login succeeded (checks the URL, looks for dashboard elements).
- Navigates to the profile settings page and inspects the available form fields.
- Ends the exploration session.
- Creates a QA plan using the discovered selectors, URLs, and verified action sequences.
At each step, the agent receives a screenshot and the page DOM, so it can identify the right elements and adapt if something unexpected happens (e.g., a modal dialog appears, a selector doesn’t match).
Exploration Logs
Section titled “Exploration Logs”Exploration sessions are logged locally so the agent can reference past discoveries.
list_exploration_logs— Lists recent sessions with timestamps, action counts, and last visited URLs.get_exploration_log— Retrieves the full action log from a specific session. Successful browser steps are formatted as a JSON array that can be directly used in a QA plan’sbrowser_steps.
Logs are stored at ~/.aqua/explorations/ and automatically cleaned up after 24 hours (up to 30 sessions per project are retained).