Turn Limits and Overrides
When Testronaut runs a mission, it interacts with the browser and the LLM in turns — one step of reasoning or action per turn.
Each turn might include reading the DOM, deciding what to do next, clicking a button, or verifying a result.
By default, missions are capped at 20 turns to prevent runaway loops, reduce cost, and keep runs predictable.
🧩 What Is a Turn?
A turn is a single agent reasoning cycle:
- Observe the current browser state (via DOM snapshot or focus section)
- Think and plan the next action
- Execute that action (e.g., click, type, navigate)
- Evaluate the result, and repeat if necessary
You can think of it like a conversation between the agent and the page:
“I see the login form.” → “I’ll fill it in.” → “I see a dashboard now — success!”
⚙️ Default Behavior
By default:
npx testronaut
runs with a maximum of 20 turns per mission.
This default is defined inside the Testronaut runtime (and can be overridden by configuration or CLI).
🔧 CLI Override
To temporarily raise or lower the limit, use the --turns flag:
npx testronaut --turns=30
This overrides both:
- the default limit, and
- any value specified in
testronaut-config.json.
💡 Example:
--turns=10→ quicker runs, fewer LLM calls--turns=40→ longer workflows, more exploration time
You’ll see confirmation in the console:
🎯 Turn override: 30
🧠 When to Tune Turn Limits
| Scenario | Recommended Limit | Rationale |
|---|---|---|
| Short, deterministic flows (e.g., login, logout, form submit) | 10–20 turns | Keeps runtime fast and cost low. |
| Exploratory missions (multi-page flows, decision trees) | 25–40 turns | Allows more reasoning steps without early cutoffs. |
| Debug or teaching missions | 40–60 turns | Helps observe agent thought process over longer runs. |
| Continuous or monitored missions | ≤15 turns | Keeps resource usage predictable in automation. |
🧭 If your missions are hitting the limit frequently, it may indicate the agent needs clearer goals or stronger page focus hints.
📉 Why Fewer Turns
- Faster feedback — runs complete in seconds instead of minutes.
- Lower cost — fewer LLM tokens and browser steps.
- Cleaner signal — reduces risk of the agent wandering off-task.
📈 Why More Turns
- Complex UIs — multi-step flows or dynamic loaders.
- Exploration — when testing unknown user paths.
- Diagnosis — seeing how far the agent gets before failure.
🧰 Tips
- Start small: 15–20 turns are usually enough for most missions.
- Increase gradually when debugging long workflows.
- Use your report viewer to inspect how turns were used — if half of them are retries, it’s usually better to adjust the mission goal rather than raise the cap.
- In CI/CD, keep limits conservative for speed and predictability.
🧮 Cost Implications
Each turn typically involves:
- One reasoning call to your chosen LLM
- One DOM extraction
- One browser action (Playwright step)
Roughly:
total_tokens_used ≈ turns × avg_tokens_per_turn
So doubling your turns often doubles token cost and execution time — tune accordingly.
🧭 Summary
| Control | Scope | Notes |
|---|---|---|
maxTurns parameter in code | Per mission | Use for static caps in mission files |
TESTRONAUT_TURNS env variable | Per environment | Useful for CI/CD tuning |
--turns=<n> CLI flag | Per run | Quick override (highest priority) |
💬 Turns are the heartbeat of Testronaut — they balance autonomy and control.
Tuning them gives you precise control over cost, runtime, and exploration depth.