Skip to main content
Version: 2.27

Workflows

This page describes the patterns that work well when collaborating with a coding agent on Cycle tests. Each workflow is described as a conversation: what you say, and what the agent does on your behalf via the Cycle MCP server.

These flows assume you have already followed the Setup instructions and your agent is connected to the Cycle MCP server.

Drafting a New Web Test from a Description​

This is the most common workflow. You describe the desired test in plain language and let the agent author a .feature file by exploring the live application.

You say:

Create a new Cycle project at C:\Users\me\Documents\CycleProjects called CatalogSmokeTest and write a test that searches our staging storefront at https://staging.example.com for "wireless headphones", opens the top result, adds it to the cart, and verifies the cart count goes from 0 to 1.

The agent does:

  1. Calls create_project to scaffold CatalogSmokeTest.cycproj and the standard project tree.
  2. Calls cycle://authoring-guide to refresh on syntax conventions.
  3. Calls run_step to launch Chrome and navigate to https://staging.example.com.
  4. Calls run_step with step_id: "WebDriver.snapshotPage" to read the live accessibility tree and finds:
    • The search field at id:search-input
    • The submit button at id:search-submit
  5. Drives the page interactively (further run_step calls for type, click, navigate) to verify the locators work.
  6. Lands on the product page, snapshots again via WebDriver.snapshotPage, finds id:add-to-cart.
  7. Writes the .feature file under the project's Test Cases/ directory.
  8. Calls validate_feature to confirm the syntax is clean.
  9. Optionally calls run_test for an end-to-end execution and reports the result.

You review the resulting .feature file in your editor and iterate.

This works because the agent never guesses at locators. It inspects the live page via run_step with WebDriver.snapshotPage before writing each one. This catches issues that pure-text-prompt-based authoring misses: dynamic IDs, accessibility-name mismatches, elements hidden behind iframes, etc.

Web Only

This step-by-step inspection currently only applies to web testing because it uses the WebDriver plugin (due to requiring steps using the plugin architecture).

Debugging a Failing Test​

When a test fails, the agent has the structured-error tooling to give you a focused fix instead of generic advice.

You say:

My LoginAndPlaceOrder.feature is failing on the third step. Run it, find out why, and propose a fix.

The agent does:

  1. Calls run_test with the feature path. The tool returns the exit code, truncated console output, and the directory containing the results .db file.
  2. Calls get_run_errors with that directory. This returns:
    • The failing step text and step ID
    • The exception class and message
    • The stack trace
    • A list of artifacts (screenshots, logs) saved during the run
  3. If the failure is "element not found," the agent re-launches the browser via run_step, navigates to the same screen, and snapshots it via WebDriver.snapshotPage to compare what the test expected with what's actually rendered.
  4. If the failure is "UnknownStep," the agent calls search_steps and get_step to find the correct step ID and parameter shape.
  5. Proposes a specific edit to the .feature file and waits for your approval before applying it.
Try Asking Directly

Directly asking the agent for artifacts can assist with debugging. Cycle saves a screenshot at the moment of failure. If your agent supports image inputs (Claude, Copilot in VS Code, Cursor), say "show me the failure screenshot" and the agent can read the PNG path from get_run_errors, open it, and reason about what went wrong visually.

Exploring an Unfamiliar Application​

When you're testing an application you don't know well, the agent can explore it with you.

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'd set the date range.

The agent does:

  1. Calls run_step to start a browser and navigate to the URL.
  2. Calls run_step with WebDriver.snapshotPage to read the page's accessibility tree.
  3. Reports what it sees in plain language: the filter combobox names, what options each one accepts, where the date pickers are.
  4. Optionally calls browser_screenshot to send you the rendered view.
  5. Suggests a .feature file structure that mirrors what it found.

This is faster and more accurate than the agent describing the page from screenshots alone, because the accessibility tree contains element roles and accessible names that screenshots don't.

Bulk-Updating an Existing Test Suite​

When a UI change breaks dozens of feature files, the agent can scan the failures and apply consistent fixes.

You say:

The Sign In button on the login page is now labeled Log In. Run all features under Test Cases/Login/, find the ones that fail because of this, and update them.

The agent does:

  1. Reads the directory listing.
  2. For each .feature file, calls run_test and checks the result.
  3. For files that fail with the expected mismatch, edits the file (using the agent's normal file-edit tools) to replace Sign In with Log In.
  4. Calls validate_feature after each edit.
  5. Re-runs the full set to confirm the fix.
  6. Reports a summary: which files were edited, which still fail (and why).

You approve or revise the changes file-by-file as the agent works through them.

Authoring a Step Plugin (Advanced)​

If you write your own step plugins (see Creating New Steps), the agent can help you author tests that use those steps once the plugin is installed in cycle-cli's plugins/ directory.

You say:

I just installed the magic-powers-plugin. Show me what new steps it added and write a smoke test that uses each one.

The agent does:

  1. Calls cycle://categories to see the new plugin's category.
  2. Calls list_steps for that category to enumerate the new steps.
  3. Calls get_step for each one to learn the parameter shape.
  4. Writes a .feature file that exercises each step in sequence.
  5. Validates and runs the feature.

The Cycle MCP server picks up plugins from the standard plugins/ directory next to cycle-cli.exe, so newly-installed plugins become available to the agent automatically without any config change. Restart the agent after installing a plugin so the server reloads.

Tips for Working with the Agent Effectively​

  • Be specific about state. "Add an item to my cart" vs. "Add the top search result for 'wireless headphones' to the cart and verify the cart count goes from 0 to 1." The second is testable; the first is wishy-washy and the agent will pick something arbitrary.
  • Always ask for validation before execution. A validate_feature round trip is cheap; a run_test round trip can take minutes if the test does anything substantial.
  • Use the live browser for any non-trivial UI. If the agent skips the page snapshot (WebDriver.snapshotPage via run_step) and writes locators from imagination, push back and tell it to inspect the page first. The setup-recommended rules file (Setup) prevents this, but rules drift — confirm the agent is using the live tooling.
  • Treat the agent's .feature files as a starting point. Read them. The agent is good at structure but may pick less-readable variable names or include redundant assertions. The CycleScript authoring guide is the source of truth for style.
  • Commit early, commit often. When the agent makes a change you like, save it to source control immediately. If the next iteration goes wrong, you can roll back without losing progress.