Intelligent App Exploration

Intelligent App Exploration is the Cycle Intelligence capability that lets an AI coding agent drive your live application one step at a time before it writes any part of a test. The agent works through the Cycle MCP Server and its run_step tool, which executes a single Cycle step in a session that stays open across calls.

In one conversation the agent finds the screens, confirms the workflow can be completed, and collects real element locators. The Feature File it produces afterward is grounded in reality rather than in theory.

Web applications only

run_step executes steps from any installed plugin, but the snapshot-driven element discovery described here comes from the WebDriver plugin. Exploration in this form therefore applies to web testing.

Why explore before authoring?

An agent that writes a test without opening the application has to invent the details it cannot know. Element locators become guesses, and each one costs another round of trial and error to correct. The test then fails for reasons that have nothing to do with the behavior under test.

Exploring first removes that whole class of rework:

• Real locators instead of plausible ones: The agent reads the page and derives a locator from what is there. Dynamic IDs, accessible names that do not match the visible text, and controls buried in iframes are all caught before they reach a .feature file.
• A workflow proven to be reachable: Driving the steps live confirms the path exists. A required field, an interstitial dialog, or a permission gate surfaces during exploration rather than during the first test run.
• Orientation in an unfamiliar application: Exploration doubles as a guided tour. Ask what controls a screen offers and how to work them, even when no test is the immediate goal.
• One session instead of a write-run-fix loop: Each failed run costs minutes. Confirming the sequence interactively front-loads that cost into a conversation you are already having.

Prerequisites

• A supported AI coding agent connected to the Cycle MCP Server (see the Cycle MCP setup guide).
• A signed-in Cycle session. The authenticate tool can help if you are signed out.
• A reachable URL or screen to start from, plus any credentials or test data the workflow needs.

If the workflow depends on records existing first, such as an order or an inventory position, set that up declaratively with a Blueprint rather than clicking it into existence. Intelligent Data covers that half of the work.

How exploration works

Exploration rests on three pieces of the Cycle MCP Server, described in full under Tools and Resources.

Piece	Role in exploration
run_step	Executes one step in a persistent live session. The browser survives between calls, so the agent can open Chrome, navigate, type, and click across many separate requests.
Step discovery resources	The agent reads cycle://categories for a category name, cycle://steps/{category} for that category's steps and their StepIDs, then cycle://step/{id} for exact parameter names.
reset_step_session	Ends the current scenario and starts a clean one when the session gets stuck, without paying the full startup cost again.

Reading an unknown-step error

The step_id that run_step takes is the StepID, such as WebDriver.navigateToUrl, and not the natural-language step text. When you see an unknown-step error in the agent's tool calls, it usually supplied a step sentence, or an ID it recalled instead of looking up.

Exploring an application

Exploration is a conversation, not a command. You describe where to start and what you want to know, and the agent drives.

You say:

Open the order management screen at https://staging.example.com/orders, walk through the filters at the top, and tell me what controls are there and how I would set the date range.

The agent:

1. Opens a browser with WebDriver.startLocal and navigates to the URL through run_step.
2. Takes an accessibility tree snapshot with WebDriver.snapshotPage to read what the page exposes.
3. Reports the controls in plain language: the name and role of each filter, and where the date pickers sit.
4. Continues driving the workflow through further run_step calls, taking a fresh snapshot after each navigation or major UI change.
5. Captures a screenshot with WebDriver.saveScreenshot when you want to see the rendered view.

Then, ask follow-up questions as it goes. "Now click the export button and tell me what happens" continues from the same page rather than starting over.

Reading a page snapshot

A snapshot is the page's accessibility tree, listing every interactive and labeled element by its ARIA role and accessible name:

- searchbox "Search Orders"
- button "Apply Filters"
- link "Export"
- heading "Results"

Roles and accessible names are exactly what a Cycle locator can target, which is why a snapshot beats a screenshot for finding elements. Each line maps onto a locator:

Snapshot line	Locator to use
- button "Apply Filters"	text:Apply Filters, or cssSelector:[role='button'][aria-label='Apply Filters']
- link "Export"	linkText:Export
- searchbox "Search Orders"	name: or id: when the page exposes one, otherwise cssSelector:[role='searchbox']

Snapshots are available in Chrome and Edge. WebDriver.snapshotPageToVariable saves the same snapshot to a variable, for when a later step needs to read or assert against it.

Recovering a wedged session

Live sessions get stuck. A modal will not dismiss, the browser ends up in a state the next step cannot recover from, or a Cycle setting needs to change before testing can continue. Ask the agent to call reset_step_session rather than fighting it with more steps.

Reset disposes the browser session, so the agent must open a new browser with WebDriver.startLocal before interacting again. It leaves the plugin and engine processes running, so recovery skips the slow 10 to 30 second startup.

Reset does not revive a crashed plugin

If run_step starts returning a connection error or a message that the process has exited, the WebDriver process itself is gone. That needs the MCP server restarted, not the session reset. See Troubleshooting.

Getting good results from exploration

• Give a concrete entry point: A URL beats an application name. If you only know the screen, say so and let the agent ask.
• Describe verifiable state: "Filter the order list to last week and confirm the result count drops" is explorable. "Look at some orders" leaves the agent choosing arbitrarily.
• Insist on the snapshot: If the agent starts producing locators without having inspected the page, tell it to snapshot first. The recommended agent rules discourage guessing, but rules can drift.
• Explore first, author second: Once the workflow runs cleanly end to end, have the agent hand the confirmed sequence to the feature-file-author subagent, which writes the .feature file and runs validate_feature until the syntax is clean.
• Read what comes back: The agent is reliable about structure and less so about naming and assertion choices. The Features section is the source of truth for CycleScript syntax and style.

Running exploration from a prompt

You do not have to compose the exploration request yourself. The Cycle MCP Server ships an author-a-test prompt that wraps this whole workflow into a single call. Describe what you want to test in one plain-language input and the prompt expands it into a structured request that has the agent restate its understanding, fill the gaps it finds, explore the running application a step at a time, and delegate authoring to the feature-file-author subagent. It also keeps a running log of the session under MCP Prompt Logs/ at the root of your Cycle project, including which steps were confirmed live and which were authored blind.

Reach for the prompt when the goal is a finished test. Explore in plain conversation when the goal is to understand an application.