Generating the Tests
A single guided prompt drives the whole conversion, so you do not have to describe the process yourself. It is the same prompt whether you already know which specifications you want or you would like help choosing them.
Each specification becomes exactly one test. The conversion never merges several specifications into a single test, which keeps every generated test traceable to one source specification.
Running the conversion
Call the conversion prompt with the folder holding your specifications and the directory to write the tests into.
/cycle:generate-tests-from-specs {bundle-root} {target-directory} {spec-paths}
| Field | Required | What to provide |
|---|---|---|
| Bundle root | Yes | Absolute path to the Test-Specs folder. |
| Target directory | Yes | Where the generated tests are written, and where existing coverage is read from. Usually the Test Cases directory of your Cycle project. |
| Spec paths | No | The specifications to convert, relative to the bundle root and separated by commas. Leave this blank to choose them with the agent instead. |
Leaving the spec paths blank is the better starting point on a bundle you do not know well. The agent then walks you through reviewing and selecting before anything is generated. Fill them in when you already know exactly which specifications you want.
If your agent does not support prompts, describe the same request in plain language and name the paths. The agent uses the same tools either way.
How the conversion proceeds
The agent works in four stages and checks in with you along the way.
1. The plan
The agent first produces a plan without writing anything. It relays the plan to you before it acts, so you can see what the conversion will do:
- The test it would generate for each selected specification, including whether that test will be authored or left as a stub.
- Any specification skipped because an existing test already covers it.
- Any selected path it could not find in the folder.
- Any target file that already exists.
The plan reports something along these lines:
Would generate 2 tests
Adjust Storage Location.feature authored covers Inventory/adjust-storage-location.md
Cycle Count.feature stub covers Inventory/cycle-count.md (3 open questions)
Skipped, already covered 1
Inventory/receive-shipment.md covered by Receive Shipment.feature
Not found 1
Inventory/does-not-exist.md
Collisions 1
Cycle Count.feature stub target exists, not overwritten
The exact wording depends on which agent you use. What matters is that every selected specification is accounted for, as a test to generate, as work already done, as a path that could not be found, or as a file the conversion will not overwrite.
Read the plan before approving it. This is the cheapest point to correct a selection.
2. Confirming collisions
If a planned stub would overwrite a file that already exists, the agent stops and tells you rather than replacing it. The same applies when a planned test's target file already exists, because authoring would overwrite that file. You decide whether to rename, choose a different specification, or confirm the overwrite.
3. Authoring
For each specification with steps, the agent hands the specification's content to the feature-file-author subagent.
That subagent owns CycleScript syntax and authoring rules.
It receives the ordered steps, the test data variables and example values, the expected results, and the setup and teardown context, which is a far richer starting point than a one-line request.
It resolves each item to a real Cycle step, supplies the parameters and locators, and validates the file's syntax itself before handing it back.
Some steps arrive at the subagent already matched to a Cycle step. A deterministic pass compares each specification step against the step catalog and pre-fills the match when exactly one step matches unambiguously. The agent reports how many steps were pre-filled and how many were left for the subagent to resolve, so you can see how much of the specification mapped mechanically.
Pre-filling records the identity of the matched step only. It never carries parameters or locators, so the subagent still supplies those. The subagent confirms every pre-filled match and replaces it when it is wrong for the context. An ambiguous or partial match is deliberately left unresolved, because a wrong match costs more than a missing one.
This conversion works from the written specification. The agent does not open your application while generating, so the locators in a generated test are derived from what the specification describes rather than confirmed against a running page.
Expect locators to be the most likely thing needing attention on the first run. That is what validation is for, and a locator failure there is a normal outcome rather than a sign the conversion went wrong.
When you want a test built against the live application from the start, describe it to the author-a-test prompt instead. That flow explores the running application before writing any locator.
4. Recording coverage
Finally, the agent writes the stubs and stamps a coverage marker into each authored test:
# Spec-Coverage: Inventory/adjust-storage-location.md
The marker names the specification the test covers. It is written as a comment, so it does not affect how the test runs.
Handling incomplete specifications
A specification with no convertible steps does not become a guessed test. It becomes a stub: a file that records what the specification contained and what remains unanswered.
A stub is a comment-only file, and it states plainly that it is not runnable yet. It contains:
- The coverage marker, so the specification is not silently converted again later.
- The open questions that must be resolved before the test can be authored, such as steps that could not be converted, a missing description, or a test data value the specification named without giving a value.
- The specification content that was found, preserved so you do not have to open the source document again.
Authored tests can carry open questions too. When a specification has steps but is missing detail, the agent authors what it can and reports the gaps rather than filling them in.
A stub is a placeholder for work, not a finished test. Resolve its open questions in the source specification, then convert it again.
Converting more specifications later
Coverage makes the flow repeatable. When you run the conversion again, the agent reads the coverage markers already present in the target directory and skips any specification an existing test covers. It reports what it skipped and why.
This means you can:
- Convert in small batches and add to the suite over time.
- Re-run the same selection safely, because already-converted specifications are skipped rather than duplicated.
- Hand the work to a teammate, because the coverage record lives in the generated tests and travels with source control.
To regenerate a test deliberately, remove or rename the existing test file first. The agent will then see the specification as uncovered.