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:

1. Observe the current browser state (via DOM snapshot or focus section)
2. Think and plan the next action
3. Execute that action (e.g., click, type, navigate)
4. 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).

---

🔁 Turn Retries

Each turn gets 2 retries by default so transient flakiness does not end a mission immediately. You can set the retry limit between 1–10:

• testronaut-config.json

  { "retryLimit": 5 }

• CLI flag

  npx testronaut --retry_limit=5

• Environment variable

  TESTRONAUT_RETRY_LIMIT=5 npx testronaut

What you’ll see:

• Clear Re-attempt X/Y labelling in logs and HTML reports — no off-by-one mysteries.
• Every attempt (including failures) is preserved in mission reports for full auditability.
• Fewer false negatives from flaky selectors or transient UI states, while keeping transparency intact.

💫 Your agent can retry intelligently, keeping the full trail of attempts without hiding the underlying behavior.

---

🔧 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.