Skip to main content

Exploratory Testing Mode

Exploratory Mode lets you give Testronaut minimal guidance (just a starting point) and allow it to explore your app freely across many turns. Instead of pursuing a single fixed goal (like “log in” or “submit a form”), it behaves like an intelligent tester observing, clicking, and recording findings as it goes.

This mode is perfect when:

  • You want to discover unexpected UI issues or navigation loops.
  • You’re onboarding a new product area and want to see what the agent explores.
  • You’ve just deployed a large UI change and want a broad sanity check.

🧠 What Happens​

When you set a large turn limit (for example, --turns=200), the agent continues reasoning and interacting until either:

  • It reports SUCCESS or FAILURE, or
  • It reaches the maximum allowed turns.

Every action: DOM inspection, click, screenshot, reasoning, is recorded as a turn.
The results are displayed in your Testronaut report, with screenshots and reasoning steps included.

🪐 Example: Exploratory Mission​

Create a mission file called exploratory.mission.js (you can change the name to whatever you want, but this is for example purposes):

import { runMissions } from 'testronaut';

export const exploratoryMission = `
Visit ${process.env.URL}.
You are in exploratory mode, navigate the interface to understand what this app does.
Click buttons, open menus, inspect pages, and capture screenshots as you go.
Look for any broken links, unexpected popups, missing labels, or console errors.
After exploring multiple areas (such as dashboards, menus, or modals), summarize your findings clearly.
End with a SUCCESS message if exploration completed without crashes or blockers,
or FAILURE if you encounter any major issues.
`;

export async function executeMission() {
  return await runMissions({
    mission: exploratoryMission
  }, "exploratory mission");
}

or for something with more guard rails (which also runs a login mission first):

import { runMissions } from 'testronaut';
import { loginMission } from './login.mission.js';

export const exploratoryMission = `
You are doing exploratory testing with a high turn budget.
Goal: discover as many meaningful UI states and potential issues as possible.

Rules of engagement:
- Do NOT navigate to external sites.
- Prefer non-destructive actions. Avoid deletes, payments, permanent data changes.
- If you encounter forms, use obviously fake data (e.g., "Test User", "test+explore@example.com").
- Take a screenshot whenever you reach a new page/major state, open a modal, or hit an error.
- If you are uncertain what to click, call 'get_dom' and infer likely nav/menu links by their text or role.
- Use small, focused actions per turn (click one thing, evaluate, repeat).
- If a page looks dynamic (spinners/toasts), wait briefly for stability before continuing.
- If the route changed or significant content appeared/disappeared, take a screenshot.

What to look for:
- Navigation coverage: top nav, sidebars, dashboard cards, settings/profile areas, and obvious primary flows.
- Broken/obscure links, 404s, visible error banners, console errors (if surfaced), or dead-end states.
- Accessibility hints: focus traps, missing labels, interactive elements not clickable by text.
- Visual issues: overlapping UI, off-screen content, obvious layout glitches.

Stop conditions (pick the earliest):
1) You have visited ~15 distinct screens/components (count modals as screens),
2) You detect a blocking error or crash view,
3) You can no longer find meaningful actions that change state.

Final report:
- If exploration criteria met without blocking errors: respond with
  "SUCCESS: <short summary>" then list:
  - Unique areas visited (bullet list)
  - Top 3–5 findings (issues/suspicions)
  - Any suggested next probes (follow-ups)
- If you were blocked or hit a crash repeatedly: respond with
  "FAILURE: <why blocked / where>" and include last screenshots context.
`;

export async function executeMission() {
  return await runMissions(
    { 
      preMission: loginMission,
      mission: exploratoryMission 
    },
    "exploratory mission"
  );
}

These mission don't tell the agent what to test specifically, just to explore and observe.

🚀 Running the Mission​

To run with an extended turn budget (so the agent can explore thoroughly):

npx testronaut exploratory.mission.js --turns=200

You can shorten or extend this limit as needed:

  • --turns=50 for a fast smoke test
  • --turns=200 for deep exploratory passes
  • --turns=500+ only for large, complex apps (may consume more tokens) only available on paid subscriptions

💡 Tips​

  • Combine with screenshots to visualize where the agent went.
  • Review the step-by-step logs in your report to see reasoning and decisions.
  • If throttling or backoff messages appear, the agent is pacing itself to stay within token limits, this is normal.

🧹 Cleanup​

After the run finishes, Testronaut automatically removes temporary step files (JSONL logs) from the tmp/ folder.
Screenshots and final reports remain in their respective folders for review.

To keep these logs, set TN_KEEP_TMP=true ahead of your mission run.

That’s it! you now have a lightweight, open-ended way to perform exploratory testing with Testronaut!