Skip to main content
Version: 2.29

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, your agent is connected to the Cycle MCP Server, and you are signed in to Cycle.

Prompts run these flows for you

Two of the workflows below (drafting a test and debugging a failure) are available as guided Prompts. If your agent supports them, the author-a-test and debug-a-failed-run prompts set up the whole flow from a single plain-language description.

Drafting a new 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:

  1. Calls create_project to scaffold CatalogSmokeTest.cycproj and the standard project tree.
  2. Reads cycle://steps to find the steps it needs, then cycle://step/{id} for exact parameter names.
  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. Hands the confirmed step sequence to the feature-file-author subagent, whose definition carries the CycleScript syntax rules and locator formats. It writes the .feature file under the project's Test Cases/ directory and runs validate_feature itself until the syntax is clean.
  8. 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, and more.

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:

  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. Reads the cycle://run-errors/{output_dir} resource for that directory (percent-encoded). 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 is actually rendered.
  4. If the failure is "UnknownStep," the agent reads the cycle://steps catalog and cycle://step/{id} 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 the cycle://run-errors/{output_dir} resource, open it, and reason about what went wrong visually.

Exploring an unfamiliar application​

When you are testing an application you do not 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 would set the date range.

The agent:

  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 captures a screenshot via run_step (for example, the WebDriver.saveScreenshot step) 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 do not.

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:

  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.

Setting up test data with a Blueprint​

When a test needs records to exist before it runs, the agent can author a Blueprint that creates them and later removes them.

You say:

Set up an outbound order with two lines in the WMS so I can test picking, then tear it down when I am finished.

The agent:

  1. Reads cycle://blueprints/setup and cycle://blueprints/authoring for the library layout and the authoring loop.
  2. Reads cycle://blueprints/schema for the field vocabulary and skims cycle://blueprints/examples for the closest worked pattern.
  3. Reads your library directly, since it is plain files: blueprint-catalog.yml to see whether a scenario already covers this, and the system configuration for its connections and default values.
  4. Drafts the Blueprint, or adapts an existing scenario when one is close.
  5. Calls blueprint_validate and fixes every finding before touching the system.
  6. Calls blueprint_run and reports the values it realized, such as blueprint-order-ordnum.
  7. Calls blueprint_teardown when you are done, once to preview what would be removed and again with confirmation to execute it.

Ask the agent to wire the result into a Feature File and it uses the Blueprint steps, so the test sets up its own data on every run rather than depending on records that already exist.

Authoring a step plugin (advanced)​

If you write your own step plugins (see Plugins), 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 installed the magic-powers-plugin. Show me what new steps it added and write a smoke test that uses each one.

The agent:

  1. Reads cycle://categories to see the new plugin's category.
  2. Reads cycle://steps/{category} for that category to enumerate the new steps.
  3. Reads cycle://step/{id} 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" versus "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 vague 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 recommended Rules file discourages 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 Features section is the source of truth for CycleScript syntax and 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.