testronaut 1.2.1 → 1.2.3

package/README.md

@@ -1,13 +1,14 @@
 # 🧑‍🚀 Testronaut
 
-**Testronaut** is an autonomous testing framework powered by OpenAI function calling and browser automation. It allows you to define mission-based tests in plain English, then runs them through a real browser to validate UI workflows.
+**Testronaut** is an autonomous testing framework powered by **LLMs and Playwright**.  
+It lets you define *mission-based tests* in plain English, then runs them through a real browser to validate UI workflows — all while generating human-readable reports.
 
 ---
 
 ## 🌌 Join the Mission Control Community
 
-Got questions, ideas, or want to share your missions?  
-Join our Discord to connect with other Testronauts, get support, and help shape the framework’s future.  
+Got questions, ideas, or missions to share?  
+Join the Discord to connect with other Testronauts, get support, and help shape the framework’s future.
 
 [![Join Discord](https://img.shields.io/badge/Join%20Us%20on%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/pBfdef92ba)
 
@@ -15,46 +16,52 @@ Join our Discord to connect with other Testronauts, get support, and help shape
 
 ## 🚀 Features
 
-- Run real-world UI flows using missions written as plain strings or functions
-- Execute entire suites with `runMissions`
-- Uses GPT-4o + Playwright to reason and interact with your app
-- Dynamic DOM injection and retry logic
-- Built-in throttling for OpenAI rate limits
-- Modular design — define tools and memory handling as you like
+- Write tests in plain English — no brittle selectors  
+- Runs real browser sessions via **Playwright**  
+- Works with **multiple LLM providers** (OpenAI, Google Gemini, and more coming)  
+- Modular tool and DOM-reasoning system  
+- Dynamic rate-limit and token-tracking logic  
+- Generates JSON + HTML reports automatically  
 
 ---
 
 ## 📖 Documentation
 
 Looking for deeper guides, API references, and examples?  
-Head over to the official Testronaut Docs:
+Check the official docs:
 
 [![Read the Docs](https://img.shields.io/badge/Read%20the%20Docs-2E8555?style=for-the-badge&logo=readthedocs&logoColor=white)](https://docs.testronaut.app)
 
-The docs cover:
-- Getting started step-by-step
-- Writing advanced missions
-- CLI options and configuration
-- Integrating with Mission Control
-- Troubleshooting & FAQs
+Includes:
+- Quickstart and setup  
+- Writing advanced missions  
+- Configuring providers and models  
+- CLI options  
+- Mission Control integration  
+- Troubleshooting and FAQs  
 
 ---
 
 ## 📦 Installation
 
-```
+```bash
 npm install -g testronaut
 ```
-Then initialize with npx, following the instructions:
-```
+
+Then initialize your project:
+
+```bash
 npx testronaut --init
 ```
-run the welcome mission:
-```
+
+Run the sample mission:
+```bash
 npx testronaut welcome.mission.js
 ```
-📁 Directory Structure
-Your project should include a missions/ folder with mission files like:
+
+---
+
+## 📁 Project Structure
 
 ```
 missions/
@@ -62,142 +69,137 @@ missions/
 ├── logout.mission.js
 └── dashboard.mission.js
 ```
-Each file exports a mission string or function and invokes runMissions.
 
-### ✍️ Writing a Mission File
-Create a file in your missions/ directory, e.g. missions/login.mission.js:
+Each mission exports a string or function and calls `runMissions`.
 
-```
+---
+
+## ✍️ Example Mission
+
+```js
 import { runMissions } from 'testronaut';
 
 export const loginMission = `
 Visit ${process.env.URL}.
-Fill the username field with ${process.env.USERNAME}. 
+Fill the username field with ${process.env.USERNAME}.
 Fill the password field with ${process.env.PASSWORD}.
-Take a screenshot.
-Submit the form.
+Click the Login button.
 Wait for the dashboard to appear.
-Take another screenshot.
-Report SUCCESS if the dashboard is loaded, otherwise report FAILURE.
+Take a screenshot.
+Report SUCCESS if the dashboard is loaded, otherwise FAILURE.
 `;
 
 export async function executeMission() {
-  await runMissions({
-    mission: loginMission
-  }, "Login Mission");
+  await runMissions({ mission: loginMission }, "Login Mission");
 }
 ```
 
-Pass in credentials using an .env file. The .env file should also include your Open AI API key (permissions to the completions endpoint required):
+Create a `.env` file with your credentials **and LLM API key** (depending on your chosen provider):
+
+```bash
+# For OpenAI
+OPENAI_API_KEY=sk-...
+
+# Or for Gemini
+GEMINI_API_KEY=AIza...
 
-```
-OPENAI_API_KEY=sk-proj-############
 URL=https://example.com/login
 USERNAME=example@example.com
 PASSWORD=********
 ```
 
-You can chain multiple phases:
+---
 
-```
-import { runMissions } from 'testronaut';
-import { loginMission } from './login.mission.js';
-import { logoutMission } from './logout.mission.js';
-import { navigateToContactFormMission } from './navigateToContactForm.mission.js';
-
-export const fillContactFormMission = 
-`Input the text "example@example.com" in the email field.
-Input the phone number (555)555-5555 into the phone number field.
-Click the submit button.
-Upon submission success there should be a toast notification indicating the form information was saved successfully.
-Take a screenshot.
-If found, report SUCCESS. Otherwise, report FAILURE.`
+## 🧠 LLM Provider Support
 
-export async function executeMission() {
-  await runMissions({
-    preMission: [loginMission, navigateToContactFormMission],
-    mission: fillContactFormMission,
-    postMission: logoutMission,
-  }, "Fill Contact Form Mission");
-}
-```
+Testronaut is provider-agnostic.  
+Choose your preferred LLM at init or via environment variables.
 
-### 🏃 Running Missions
-Run all missions in the missions/ directory:
+```bash
+# During init
+npx testronaut --init
 
+# Or override anytime
+TESTRONAUT_PROVIDER=gemini TESTRONAUT_MODEL=gemini-2.5-pro npx testronaut
 ```
+
+Current supported providers:
+
+| Provider | Example Models |
+|-----------|----------------|
+| **OpenAI** | gpt-4o, gpt-4.1, o3, gpt-5, etc. |
+| **Google Gemini** | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-8b |
+
+More providers coming soon (Anthropic, Mistral, etc.).
+
+---
+
+## 🏃 Running Missions
+
+Run all missions:
+```bash
 npx testronaut
 ```
-Run a specific file:
 
-```
+Run a specific mission:
+```bash
 npx testronaut login.mission.js
 ```
 
-🧰 Available Helpers
-
-```
-runMissions({ preMission, mission, postMission }) 
+Chain missions together:
+```js
+await runMissions({
+  preMission: [loginMission],
+  mission: fillContactFormMission,
+  postMission: logoutMission,
+}, "Contact Form Flow");
 ```
-– Runs test phases
+---
 
-```
-mission(name, fn) and objective(desc, workflow) 
-```
-– Optional suite syntax
+## 📋 Reports
+
+Testronaut generates both JSON and HTML reports automatically under:
 
 ```
-runSuite(objectives)
+missions/mission_reports/
 ```
-– Executes all registered test objectives
-
-### 📋 Reports
-HTML and JSON reports automatically created in the ```missions/mission_reports/``` directory for each testronaut run
 
-### 🧪 Under the Hood
-Uses Playwright for browser automation
+Each includes:
+- Steps executed
+- Token usage
+- Screenshots
+- Pass/Fail summaries
 
-Interacts with OpenAI’s GPT-4o via Function Calling
+---
 
-Supports modular tool definitions via CHROME_TOOL_MAP
+## 🧪 Under the Hood
 
-🔧 Developing Locally
-Clone and install locally:
+- **Playwright** for browser automation  
+- **LLMs** for reasoning, DOM parsing, and tool use  
+- **Token throttling** + adaptive cooldowns  
+- **Extensible architecture** for custom tools and workflows  
 
-```
-npm install
-npm link
-```
-Now you can use testronaut in any local project.
+---
 
-### 📄 License
-MIT
+## 🧭 Mission Control
 
---
+[Mission Control](https://mission.testronaut.app) lets you:
+- View all reports in one dashboard  
+- Track mission history and success rates  
+- Compare results across environments  
+- Access screenshots and step details anytime  
 
-### 📊 Track Your Missions Over Time
-Want to see your test results evolve, spot trends, and keep all your reports in one place?  
-Sign up for **Mission Control** — your personal dashboard for Testronaut.
+---
 
-With Mission Control you can:
-- 📈 Track your mission reports historically
-- 🔍 Drill into past runs with full step-by-step details
-- 🛠️ Compare results between different builds or environments
-- ☁️ Access reports from anywhere, without digging through local files
+## 📄 License
 
-Getting started is simple:
-1. [![Sign up for Mission Control](https://img.shields.io/badge/Sign%20Up%20for%20Mission%20Control-0A84FF?style=for-the-badge&logo=rocket&logoColor=white)](https://mission.testronaut.app)
-2. Link your account to Testronaut CLI
-3. Watch your mission history grow!
+MIT
 
 ---
 
 ## ☕ Support the Mission
-🤖 Built with ❤️ by [Shane Fast](https://github.com/scfast)
 
-If Testronaut has helped you save time or improve your testing, consider fueling the mission!  
-Your support helps cover hosting, development time, and the occasional coffee needed to debug at 2am.
+🤖 Built with ❤️ by [Shane Fast](https://github.com/scfast)
 
+If Testronaut saves you time, consider fueling the mission:  
 [![Donate](https://img.shields.io/badge/Donate-Coffee%20Fuel%20for%20Testronaut-ff813f?style=for-the-badge&logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/testronaut)
-
----

package/bin/cli.js

@@ -1,4 +1,37 @@
 #!/usr/bin/env node
+
+/**
+ * cli.js
+ * -------
+ * Purpose:
+ *   Single entry point for the Testronaut CLI:
+ *   - Parses flags (e.g., --model, --turns, --init, help).
+ *   - Runs mission files (single or all), aggregates results, and writes HTML/JSON reports.
+ *   - Provides subcommands: login, upload (report + screenshots), serve/view (static file server).
+ *
+ * Key flags:
+ *   --model <id> / --model=<id>         → sets TESTRONAUT_MODEL env (wins over config file)
+ *   --turns <n> / --turns=<n>           → sets TESTRONAUT_TURNS env (wins over config file)
+ *   --init                               → scaffolds project + optional Playwright browsers
+ *   --help                               → prints help
+ *
+ * Notable helpers (defined below):
+ *   parseJsonSafe(res, label)            → tolerant JSON parse with good error messages
+ *   pkgManagerForCwd(cwd)                → detects npm/pnpm/yarn/bun
+ *   hasAny(modNames)                     → “do we have at least one of these deps?” (ESM-safe)
+ *   installDev(pm, pkg)                  → dev-install a package with the detected package manager
+ *   ensurePlaywrightInstalled()          → install @playwright/test and browsers (skippable in CI)
+ *   guessMimeType(p)                     → static server content types
+ *   safeJoin(root, relUrlPath)           → path traversal protection for static server
+ *   findLatestReportPair(reportDir)      → find latest run_<ts>.html (+ matching .json if present)
+ *   serveLatestReport()                  → read-only file server for most recent HTML report
+ *
+ * Test strategy:
+ *   To test pure helpers without running the whole CLI, we export a tiny test bundle:
+ *     export const __test__ = { guessMimeType, safeJoin, findLatestReportPair, pkgManagerForCwd }
+ *   See tests in tests/cliTests/cli.helpers.test.js
+ */
+
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -46,6 +79,29 @@ if (modelFlagIndex >= 0) {
   args.splice(modelFlagIndex, modelOverride ? 2 : 1);
 }
 
+// Look for --turns=<n> or --turns <n>
+let turnsOverride;
+const turnsFlagIndex = args.findIndex(a => a === '--turns' || a.startsWith('--turns='));
+if (turnsFlagIndex >= 0) {
+  if (args[turnsFlagIndex].includes('=')) {
+    turnsOverride = args[turnsFlagIndex].split('=')[1];
+  } else if (args[turnsFlagIndex + 1]) {
+    turnsOverride = args[turnsFlagIndex + 1];
+  }
+
+  if (turnsOverride) {
+    const n = Number(turnsOverride.trim());
+    if (Number.isFinite(n) && n > 0) {
+      process.env.TESTRONAUT_TURNS = String(n);
+      console.log(`🎯 Turn override: ${process.env.TESTRONAUT_TURNS}`);
+    } else {
+      console.warn(`⚠️ Invalid --turns value "${turnsOverride}". Ignoring.`);
+    }
+  }
+
+  // Remove flag & value so they aren’t treated as filenames
+  args.splice(turnsFlagIndex, turnsOverride ? 2 : 1);
+}
 
 const missionsDir = path.resolve(process.cwd(), 'missions');
 
@@ -66,6 +122,7 @@ Usage:
 
 Options:
   --init                    Scaffold project folders and a welcome mission
+  --turns=<n>               Override max turns for this run (e.g., --turns=30)
   --help                    Show this help message
 
 Examples:
@@ -228,7 +285,13 @@ fs.mkdirSync(outputDir, { recursive: true });
 fs.writeFileSync(`${outputDir}/${runId}.json`, JSON.stringify(report, null, 2));
 generateHtmlReport(report, `${outputDir}/${runId}.html`);
 
-// helpers near top of cli.js
+/**
+ * Parse a fetch Response safely and return JSON or throw a rich error.
+ * @param {Response} res
+ * @param {string} urlLabel - human-friendly label for error messages
+ * @returns {Promise<any>}
+ * @throws when HTTP status is not ok or body is empty/invalid
+ */
 async function parseJsonSafe(res, urlLabel) {
   const text = await res.text(); // read once
   let data = null;
@@ -248,6 +311,11 @@ async function parseJsonSafe(res, urlLabel) {
   return data;
 }
 
+/**
+ * Detect the local package manager based on lockfiles.
+ * @param {string} [cwd=process.cwd()]
+ * @returns {'pnpm'|'yarn'|'bun'|'npm'}
+ */
 function pkgManagerForCwd(cwd = process.cwd()) {
   const has = (f) => fs.existsSync(path.join(cwd, f));
   if (has('pnpm-lock.yaml')) return 'pnpm';
@@ -559,7 +627,11 @@ async function uploadReport() {
   }
 }
 
-
+/**
+ * Guess a reasonable MIME type for static serving.
+ * @param {string} p - file path
+ * @returns {string}
+ */
 function guessMimeType(p) {
   const ext = path.extname(p).toLowerCase();
   if (ext === '.html' || ext === '.htm') return 'text/html; charset=utf-8';
@@ -574,6 +646,12 @@ function guessMimeType(p) {
   return 'application/octet-stream';
 }
 
+/**
+ * Path-join a request path to a root directory with traversal protection.
+ * @param {string} root - filesystem directory
+ * @param {string} relUrlPath - URL path from incoming request
+ * @returns {string|null} resolved path or null on attempted escape
+ */
 function safeJoin(root, relUrlPath) {
   // Prevent path traversal and keep within root
   const decoded = decodeURIComponent(relUrlPath);
@@ -593,6 +671,12 @@ async function openInBrowser(targetUrl) {
   return exec(`xdg-open ${quoted}`).catch(() => {}); // best-effort on Linux
 }
 
+/**
+ * Find the latest run HTML (and its matching JSON, if present).
+ * Expects files like "run_<timestamp>.html" in the report directory.
+ * @param {string} reportDir
+ * @returns {{htmlFile:string, jsonFile:string|null}|null}
+ */
 function findLatestReportPair(reportDir) {
   if (!fs.existsSync(reportDir)) return null;
   const files = fs.readdirSync(reportDir).filter(f => f.endsWith('.html'));

package/core/agent.js

@@ -1,18 +1,56 @@
+/**
+ * agent.js
+ * --------
+ * Purpose:
+ *   Orchestrate a browser-backed autonomous agent over a sequence of goals.
+ *
+ * Responsibilities:
+ *   - Start/stop the browser lifecycle.
+ *   - For each goal, construct initial messages and invoke turnLoop().
+ *   - Collect per-goal traces into a normalized missionResults array.
+ *
+ * Message contract (initial):
+ *   messages = [
+ *     { role: 'system', content: 'instructions...' },
+ *     { role: 'user',   content: <goal text> }
+ *   ]
+ *
+ * Related tests:
+ *   tests/agentTests/agent.test.js
+ *
+ * Used by:
+ *   - cli/testronaut.js (runMissions)
+ */
+
 import 'dotenv/config';
 import { ChromeBrowser } from '../tools/chromeBrowser.js';
 import { turnLoop } from './turnLoop.js';
 
-export async function runAgent(goals, missionName, maxTurns = 20, ) {
+/**
+ * Execute goals with a browser agent.
+ *
+ * @param {Array<{goal:any, submissionType?:string, submissionName?:string, label?:string}>} goals
+ * @param {string} missionName
+ * @param {number} [maxTurns=20] - upper bound for turnLoop per goal
+ * @returns {Promise<Array<{missionName:string, submissionType:string, submissionName:string|null, status:'passed'|'failed', steps:any[], startTime:number, endTime:number}>>}
+ */
+export async function runAgent(goals, missionName, maxTurns = 20) {
   const browser = new ChromeBrowser();
   await browser.start();
-  const startTime = Date.now();
   let result;
 
   try {
     const missionResults = [];
+
     for (const goal of goals) {
-      // console.log(`\n🚀 Running Agent with goal:\n${goal}\n`);
       const steps = [];
+
+      // Ensure user message is a string (functions/objects → toString fallback)
+      const userContent =
+        typeof goal.goal === 'string'
+          ? goal.goal
+          : goal?.goal?.toString?.() ?? String(goal.goal);
+
       const messages = [
         {
           role: 'system',
@@ -29,61 +67,39 @@ export async function runAgent(goals, missionName, maxTurns = 20, ) {
             After completing the goal, respond with a final plain-text message starting with SUCCESS or FAILURE.
           `.trim(),
         },
-        { role: 'user', content: goal.goal },
+        { role: 'user', content: userContent },
       ];
 
+      // Run the turn loop for this goal
       result = await turnLoop(
-        browser, 
-        messages, 
-        maxTurns, 
-        0, /* currentTurn */
-        0, /* retryCount */
-        null, /* currentStep */
-        {
-          steps,          // 👈 pass in
-          missionName,    // 👈 pass in (for tagging)
-        }
+        browser,
+        messages,
+        maxTurns,
+        0,    // currentTurn
+        0,    // retryCount
+        null, // currentStep
+        { steps, missionName }
       );
-      
+
+      // Snapshot steps (avoid retaining references to mutable arrays)
       missionResults.push({
         missionName,
         submissionType: goal.submissionType || goal.label,
         submissionName: goal.submissionName || null,
         status: result?.success ? 'passed' : 'failed',
-        steps: JSON.parse(JSON.stringify(steps)), // 👈 deep-clone to avoid refs
-        startTime: Date.now() - 1, // set real values if you have them
+        steps: JSON.parse(JSON.stringify(steps)), // deep-clone
+        startTime: Date.now() - 1, // TODO: wire actual timings if needed
         endTime: Date.now(),
       });
 
-      if (!result.success) {
+      if (!result?.success) {
         console.log('🛑 Agent stopped due to failed goal.\n');
         return missionResults;
       }
-
-      // if (!result.success) {
-      //   console.log('🛑 Agent stopped due to failed goal.\n');
-      //   const endTime = Date.now();
-      //   return {
-      //     missionName: missionName,
-      //     status: 'failed',
-      //     steps: result.steps,
-      //     startTime: startTime,
-      //     endTime: endTime,
-      //   };
-      // }
     }
 
     console.log('✅ All goals completed successfully.\n');
-    // const endTime = Date.now();
     return missionResults;
-    // return {
-    //   missionName: missionName,
-    //   status: 'passed',
-    //   steps: result.steps,
-    //   startTime: startTime,
-    //   endTime: endTime,
-    // };
-
   } finally {
     await browser.close();
   }

package/core/config.js

@@ -0,0 +1,146 @@
+/**
+ * config.js
+ * ----------
+ * Purpose:
+ *   Centralized config loading and turn-budget guardrails for Testronaut.
+ *
+ * Responsibilities:
+ *   - Load `testronaut-config.json` (best effort).
+ *   - Read specific knobs with safe fallbacks (e.g., maxTurns).
+ *   - Define baseline limits (soft/hard/min/idle/errors/time).
+ *   - Enforce user requests via clamp + warn (default) or fail-fast (strict).
+ *
+ * Related tests:
+ *   tests/configTests/config.test.js
+ *
+ * Used by:
+ *   - cli/testronaut.js (to derive effectiveMax turns per run)
+ *   - core/agent.js / core/turnLoop.js (runtime stop conditions)
+ */
+
+// core/config.js
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Load testronaut-config.json from the given cwd.
+ * Returns {} when missing or invalid JSON.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<object>}
+ */
+export async function loadConfig(cwd = process.cwd()) {
+  try {
+    const raw = await readFile(path.join(cwd, 'testronaut-config.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    // No config or invalid JSON — fall back to defaults at call sites
+    return {};
+  }
+}
+
+/**
+ * Resolve the requested maxTurns from config with a safe fallback.
+ *
+ * @param {object} cfg
+ * @param {number} [fallback=20]
+ * @returns {number}
+ */
+export function getMaxTurns(cfg, fallback = 20) {
+  const n = Number(cfg?.maxTurns);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return n;
+}
+
+/**
+ * Baseline limits for mission runs. Adjust here for global defaults.
+ *
+ * @returns {{
+ *   softMaxTurns:number,
+ *   hardMaxTurns:number,
+ *   hardMinTurns:number,
+ *   maxIdleTurns:number,
+ *   maxErrors:number,
+ *   maxSeconds:number
+ * }}
+ */
+export function resolveTurnLimits() {
+  const softMaxTurns   = 50;
+  const hardMaxTurns   = 200;
+  const hardMinTurns   = 5;
+  const maxIdleTurns   = 6;
+  const maxErrors      = 5;
+  const maxSeconds     = 600; //10 minutes
+
+  return {
+    softMaxTurns,
+    hardMaxTurns,
+    hardMinTurns,
+    maxIdleTurns,
+    maxErrors,
+    maxSeconds,
+  };
+}
+
+/**
+ * Compute an effective turn budget and normalized limits from config.
+ * - Default: clamp + warn (lenient).
+ * - Strict mode (cfg.strictLimits or env STRICT_LIMITS): throw on violations.
+ *
+ * @param {object} cfg
+ * @param {ReturnType<typeof resolveTurnLimits>} [baseLimits=resolveTurnLimits()]
+ * @returns {{
+ *   effectiveMax:number,
+ *   limits: ReturnType<typeof resolveTurnLimits>,
+ *   notes:string[],
+ *   strict:boolean
+ * }}
+ */
+export function enforceTurnBudget(cfg, baseLimits = resolveTurnLimits()) {
+  const strict = !!(cfg?.strictLimits || process.env.STRICT_LIMITS);
+
+  const limits = { ...baseLimits };
+  const notes = [];
+
+  // Normalize soft/hard ordering
+  if (limits.softMaxTurns > limits.hardMaxTurns) {
+    if (strict) throw new Error(`[limits] softMaxTurns (${limits.softMaxTurns}) > hardMaxTurns (${limits.hardMaxTurns}).`);
+    notes.push(`Adjusted softMaxTurns down to hardMaxTurns (${limits.hardMaxTurns}).`);
+    limits.softMaxTurns = limits.hardMaxTurns;
+  }
+  if (limits.hardMinTurns > limits.softMaxTurns) {
+    if (strict) throw new Error(`[limits] hardMinTurns (${limits.hardMinTurns}) > softMaxTurns (${limits.softMaxTurns}).`);
+    notes.push(`Adjusted hardMinTurns down to softMaxTurns (${limits.softMaxTurns}).`);
+    limits.hardMinTurns = limits.softMaxTurns;
+  }
+
+  // Resolve requested maxTurns (env override wins over config)
+  const envTurns = Number(process.env.TESTRONAUT_TURNS);
+  const hasEnv = Number.isFinite(envTurns) && envTurns > 0;
+  const cfgTurns = Number(cfg?.maxTurns);
+  const hasCfg = Number.isFinite(cfgTurns) && cfgTurns > 0;
+  let requested = hasEnv ? envTurns : (hasCfg ? cfgTurns : 20);
+  let effectiveMax = requested;
+
+  if (hasEnv) {
+    notes.push(`ℹ️ Using CLI turn override (TESTRONAUT_TURNS=${envTurns}).`);
+  }
+
+  if (effectiveMax > limits.hardMaxTurns) {
+    const msg = `maxTurns (${effectiveMax}) exceeds hardMaxTurns (${limits.hardMaxTurns}).`;
+    if (strict) throw new Error(`[limits] ${msg}`);
+    notes.push(`⚠️ ${msg} Clamping to ${limits.hardMaxTurns}.`);
+    effectiveMax = limits.hardMaxTurns;
+  } else if (effectiveMax > limits.softMaxTurns) {
+    const msg = `maxTurns (${effectiveMax}) exceeds softMaxTurns (${limits.softMaxTurns}).`;
+    if (strict) throw new Error(`[limits] ${msg}`);
+    notes.push(`⚠️ ${msg} Proceeding, but consider lowering to control cost.`);
+  } else if (effectiveMax < limits.hardMinTurns) {
+    const msg = `maxTurns (${effectiveMax}) is below hardMinTurns (${limits.hardMinTurns}).`;
+    if (strict) throw new Error(`[limits] ${msg}`);
+    notes.push(`⚠️ ${msg} Raising to ${limits.hardMinTurns}.`);
+    effectiveMax = limits.hardMinTurns;
+  }
+
+  return { effectiveMax, limits, notes, strict };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "./bin/cli.js"

package/runner/testronaut.js

@@ -1,27 +1,49 @@
-import { runAgent } from '../core/agent.js';
-import { redactPasswordInText } from '../core/redaction.js';
-// import { runSuite } from './suiteRunner.js';
-
-// const objectives = [];
-
-// export function mission(title, fn) {
-//   console.log(`\n🚀 Mission: ${title}`);
-//   fn();
-// }
-
-// export function objective(desc, workflow) {
-//   objectives.push({ name: desc, workflow });
-// }
-
-// export async function launch(preMissionSetup) {
-//   await runSuite(objectives, preMissionSetup);
-// }
-
+/**
+ * testronaut.js
+ * -------------
+ * Purpose:
+ *   High-level mission runner: normalize pre/main/post submissions,
+ *   compute a safe turn budget from config, and invoke the agent.
+ *
+ * Responsibilities:
+ *   - Read config once and derive turn limits via enforceTurnBudget().
+ *   - Build a normalized list of submissions with human-friendly names.
+ *   - Redact sensitive text when logging mission strings.
+ *   - Call runAgent(goals, missionName, maxTurns) and post-process status.
+ *
+ * Message contract (goal → initial messages inside agent):
+ *   - system: operational guidance + success/failure contract
+ *   - user:   the mission text (or coerced string)
+ *
+ * Related tests:
+ *   tests/missionTests/testronaut.test.js
+ *
+ * Used by:
+ *   - CLI entrypoint(s)
+ */
 
 
+import { runAgent } from '../core/agent.js';
+import { redactPasswordInText } from '../core/redaction.js';
+import { loadConfig, enforceTurnBudget } from '../core/config.js';
+
+/**
+ * Run a mission flow.
+ *
+ * @param {{ preMission?: any|any[], mission?: any|any[], postMission?: any|any[] }} params
+ * @param {string} missionName
+ */
 export async function runMissions({ preMission, mission, postMission }, missionName) {
-  const normalizeToArray = (x) => (Array.isArray(x) ? x : x ? [x] : []);
+  // 1) Config and turn budget (with guardrails)
+  const cfg = await loadConfig();
+  const { effectiveMax, limits, notes } = enforceTurnBudget(cfg);
+  const maxTurns = effectiveMax;
+  if (notes.length) {
+    console.warn(notes.join('\n'));
+  }
 
+  // 2) Normalize submissions
+  const normalizeToArray = (x) => (Array.isArray(x) ? x : x ? [x] : []);
   const pre  = normalizeToArray(preMission);
   const main = normalizeToArray(mission);
   const post = normalizeToArray(postMission);
@@ -100,7 +122,8 @@ export async function runMissions({ preMission, mission, postMission }, missionN
     })
   );
 
-  const success = await runAgent(goals, missionName);
+  // 3) Execute
+  const success = await runAgent(goals, missionName, maxTurns);
   if (!success) {
     console.log(`❌ Aborting after failed goal.`);
     return;

package/tests/coreTests/agent.test.js

@@ -0,0 +1,127 @@
+// tests/coreTests/agent.test.js
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// 1) Provide a constructable mock without using `vi` inside the factory.
+vi.mock('../../tools/chromeBrowser.js', () => {
+  function ChromeBrowser() {}
+  ChromeBrowser.prototype.start = async function () {};
+  ChromeBrowser.prototype.close = async function () {};
+  return { ChromeBrowser };
+});
+
+// Keep turnLoop simple; using vi is fine here (no factory-hoist issue)
+vi.mock('../../core/turnLoop.js', () => ({
+  turnLoop: vi.fn(),
+}));
+
+import { ChromeBrowser } from '../../tools/chromeBrowser.js';
+import { turnLoop } from '../../core/turnLoop.js';
+import { runAgent } from '../../core/agent.js';
+
+let startSpy, closeSpy;
+
+describe('core/agent.runAgent', () => {
+  beforeEach(() => {
+    // 2) Spy on prototype methods AFTER import time
+    startSpy = vi.spyOn(ChromeBrowser.prototype, 'start').mockResolvedValue();
+    closeSpy = vi.spyOn(ChromeBrowser.prototype, 'close').mockResolvedValue();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    startSpy.mockRestore();
+    closeSpy.mockRestore();
+  });
+
+  it('runs all goals and returns missionResults (all passed)', async () => {
+    turnLoop
+      .mockResolvedValueOnce({ success: true })
+      .mockResolvedValueOnce({ success: true });
+
+    const goals = [
+      { goal: 'Do A', submissionType: 'mission', submissionName: 'A' },
+      { goal: 'Do B', submissionType: 'mission', submissionName: 'B' },
+    ];
+
+    const res = await runAgent(goals, 'My Mission', 10);
+
+    // Browser lifecycle
+    expect(startSpy).toHaveBeenCalledTimes(1);
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+
+    // turnLoop called once per goal and receives maxTurns
+    expect(turnLoop).toHaveBeenCalledTimes(2);
+    expect(turnLoop.mock.calls[0][2]).toBe(10);
+    expect(turnLoop.mock.calls[1][2]).toBe(10);
+
+    expect(res).toHaveLength(2);
+    expect(res[0].status).toBe('passed');
+    expect(res[1].status).toBe('passed');
+  });
+
+  it('stops early on first failure and returns partial results', async () => {
+    turnLoop.mockResolvedValueOnce({ success: false });
+
+    const res = await runAgent(
+      [
+        { goal: 'A', submissionType: 'mission', submissionName: 'A' },
+        { goal: 'B', submissionType: 'mission', submissionName: 'B' },
+      ],
+      'Fail Mission',
+      7
+    );
+
+    expect(turnLoop).toHaveBeenCalledTimes(1);
+    expect(res).toHaveLength(1);
+    expect(res[0].status).toBe('failed');
+  });
+
+  it('coerces non-string goal to string for the user message', async () => {
+    turnLoop.mockResolvedValueOnce({ success: true });
+
+    await runAgent([{ goal: { toString: () => 'coerced text' } }], 'Coerce', 5);
+
+    const messages = turnLoop.mock.calls[0][1];
+    expect(messages[1]).toEqual({ role: 'user', content: 'coerced text' });
+  });
+
+  it('deep-clones steps so external mutations do not leak', async () => {
+    turnLoop.mockImplementationOnce(async (browser, messages, maxTurns, ct, rc, cs, ctx) => {
+      ctx.steps.push({ result: 'SUCCESS: step1' });
+      return { success: true };
+    });
+
+    const res1 = await runAgent([{ goal: 'Check clone' }], 'Clone Test', 3);
+    res1[0].steps[0].result = 'TAMPERED';
+
+    turnLoop.mockImplementationOnce(async (browser, messages, maxTurns, ct, rc, cs, ctx) => {
+      ctx.steps.push({ result: 'SUCCESS: step2' });
+      return { success: true };
+    });
+
+    const res2 = await runAgent([{ goal: 'Check clone' }], 'Clone Test 2', 3);
+    expect(res1[0].steps[0].result).toBe('TAMPERED');
+    expect(res2[0].steps[0].result).toBe('SUCCESS: step2');
+  });
+
+  it('includes missionName and submission metadata in results', async () => {
+    turnLoop.mockResolvedValueOnce({ success: true });
+
+    const res = await runAgent(
+      [
+        {
+          goal: 'Meta',
+          submissionType: 'mission',
+          submissionName: 'MetaName',
+          label: 'legacy-label',
+        },
+      ],
+      'MetaMission',
+      4
+    );
+
+    expect(res[0].missionName).toBe('MetaMission');
+    expect(res[0].submissionType).toBe('mission');
+    expect(res[0].submissionName).toBe('MetaName');
+  });
+});

package/tests/coreTests/config.test.js

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+}));
+
+import { readFile } from 'node:fs/promises';
+import {
+  loadConfig,
+  getMaxTurns,
+  resolveTurnLimits,
+  enforceTurnBudget,
+} from '../../core/config.js';
+
+describe('core/config', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    delete process.env.STRICT_LIMITS;
+  });
+
+  describe('loadConfig', () => {
+    it('parses JSON when present', async () => {
+      readFile.mockResolvedValueOnce(JSON.stringify({ maxTurns: 33 }));
+      const cfg = await loadConfig('/any');
+      expect(cfg).toEqual({ maxTurns: 33 });
+    });
+
+    it('returns {} on ENOENT', async () => {
+      readFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const cfg = await loadConfig('/missing');
+      expect(cfg).toEqual({});
+    });
+
+    it('returns {} on invalid JSON', async () => {
+      readFile.mockResolvedValueOnce('{ nope ');
+      const cfg = await loadConfig('/bad');
+      expect(cfg).toEqual({});
+    });
+  });
+
+  describe('getMaxTurns', () => {
+    it('uses fallback when invalid or missing', () => {
+      expect(getMaxTurns({}, 20)).toBe(20);
+      expect(getMaxTurns({ maxTurns: 'x' }, 20)).toBe(20);
+      expect(getMaxTurns({ maxTurns: 0 }, 20)).toBe(20);
+      expect(getMaxTurns({ maxTurns: -5 }, 20)).toBe(20);
+    });
+
+    it('returns numeric when valid', () => {
+      expect(getMaxTurns({ maxTurns: 7 }, 20)).toBe(7);
+      expect(getMaxTurns({ maxTurns: '15' }, 20)).toBe(15);
+    });
+  });
+
+  describe('resolveTurnLimits', () => {
+    it('returns expected defaults', () => {
+      const l = resolveTurnLimits();
+      expect(l.softMaxTurns).toBe(50);
+      expect(l.hardMaxTurns).toBe(200);
+      expect(l.hardMinTurns).toBe(5);
+      expect(l.maxIdleTurns).toBe(6);
+      expect(l.maxErrors).toBe(5);
+      expect(l.maxSeconds).toBe(600);
+    });
+  });
+
+  describe('enforceTurnBudget (lenient)', () => {
+    it('clamps > hardMaxTurns', () => {
+      const cfg = { maxTurns: 1000 };
+      const { effectiveMax, limits, notes, strict } = enforceTurnBudget(cfg);
+      expect(strict).toBe(false);
+      expect(effectiveMax).toBe(limits.hardMaxTurns);
+      expect(notes.join('\n')).toMatch(/Clamping to/i);
+    });
+
+    it('warns when > softMaxTurns but <= hardMaxTurns', () => {
+      const cfg = { maxTurns: 120 };
+      const { effectiveMax, limits, notes } = enforceTurnBudget(cfg);
+      expect(effectiveMax).toBe(120);
+      expect(notes.join('\n')).toMatch(/exceeds softMaxTurns/i);
+      expect(effectiveMax).toBeLessThanOrEqual(limits.hardMaxTurns);
+    });
+
+    it('raises to hardMinTurns when below minimum', () => {
+      const cfg = { maxTurns: 1 };
+      const { effectiveMax, limits, notes } = enforceTurnBudget(cfg);
+      expect(effectiveMax).toBe(limits.hardMinTurns);
+      expect(notes.join('\n')).toMatch(/Raising to/i);
+    });
+
+    it('normalizes soft>hard ordering with a note', () => {
+      const weird = {
+        softMaxTurns: 300,
+        hardMaxTurns: 200,
+        hardMinTurns: 5,
+        maxIdleTurns: 6,
+        maxErrors: 5,
+        maxSeconds: 600,
+      };
+      const { limits, notes } = enforceTurnBudget({ maxTurns: 20 }, weird);
+      expect(limits.softMaxTurns).toBe(limits.hardMaxTurns);
+      expect(notes.join('\n')).toMatch(/Adjusted softMaxTurns down to hardMaxTurns/);
+    });
+  });
+
+  describe('enforceTurnBudget (strict)', () => {
+    it('throws when > hardMaxTurns', () => {
+      const cfg = { maxTurns: 999, strictLimits: true };
+      expect(() => enforceTurnBudget(cfg)).toThrow(/exceeds hardMaxTurns/i);
+    });
+
+    it('throws when below hardMinTurns', () => {
+      process.env.STRICT_LIMITS = '1';
+      const cfg = { maxTurns: 2 };
+      expect(() => enforceTurnBudget(cfg)).toThrow(/below hardMinTurns/i);
+    });
+
+    it('throws when softMaxTurns > hardMaxTurns', () => {
+      const bad = {
+        softMaxTurns: 300,
+        hardMaxTurns: 200,
+        hardMinTurns: 5,
+        maxIdleTurns: 6,
+        maxErrors: 5,
+        maxSeconds: 600,
+      };
+      expect(() => enforceTurnBudget({ strictLimits: true, maxTurns: 20 }, bad))
+        .toThrow(/softMaxTurns .* > hardMaxTurns/);
+    });
+  });
+
+
+    describe('enforceTurnBudget env override', () => {
+    const old = process.env.TESTRONAUT_TURNS;
+
+    beforeEach(() => { delete process.env.TESTRONAUT_TURNS; });
+    afterEach(() => { if (old === undefined) delete process.env.TESTRONAUT_TURNS; else process.env.TESTRONAUT_TURNS = old; });
+
+    it('uses TESTRONAUT_TURNS over cfg.maxTurns', () => {
+        process.env.TESTRONAUT_TURNS = '30';
+        const { effectiveMax, notes } = enforceTurnBudget({ maxTurns: 5 });
+        expect(effectiveMax).toBe(30);
+        expect(notes.join('\n')).toMatch(/CLI turn override/i);
+    });
+    });
+});

package/tests/runnerTests/testronaut.test.js

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mocks
+vi.mock('../../core/agent.js', () => ({ runAgent: vi.fn() }));
+vi.mock('../../core/redaction.js', () => ({
+  // simple deterministic redaction stub
+  redactPasswordInText: (s) => String(s).replace(/password:\s*\S+/gi, 'password: ********'),
+}));
+vi.mock('../../core/config.js', () => ({
+  loadConfig: vi.fn(),
+  enforceTurnBudget: vi.fn(),
+}));
+
+import { runAgent } from '../../core/agent.js';
+import { loadConfig, enforceTurnBudget } from '../../core/config.js';
+
+// Adjust the import path if your file lives elsewhere
+import { runMissions } from '../../runner/testronaut.js';
+
+describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('passes effectiveMax to runAgent and logs any notes', async () => {
+    loadConfig.mockResolvedValue({ maxTurns: 999 });
+    enforceTurnBudget.mockReturnValue({
+      effectiveMax: 200,
+      limits: { softMaxTurns: 50, hardMaxTurns: 200, hardMinTurns: 5 },
+      notes: ['⚠️ maxTurns (999) exceeds hardMaxTurns (200). Clamping to 200.'],
+      strict: false,
+    });
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    runAgent.mockResolvedValue([
+      { steps: [{ result: 'SUCCESS: done' }], status: 'passed' },
+    ]);
+
+    await runMissions({ mission: 'Do xyz' }, 'Budgeted Run');
+
+    expect(loadConfig).toHaveBeenCalledTimes(1);
+    expect(enforceTurnBudget).toHaveBeenCalledWith({ maxTurns: 999 });
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('Clamping to 200')
+    );
+    expect(runAgent).toHaveBeenCalledWith(
+      expect.any(Array), 'Budgeted Run', 200
+    );
+
+    warn.mockRestore();
+    log.mockRestore();
+  });
+
+  it('does not warn when no notes are returned', async () => {
+    loadConfig.mockResolvedValue({ maxTurns: 20 });
+    enforceTurnBudget.mockReturnValue({
+      effectiveMax: 20,
+      limits: { softMaxTurns: 50, hardMaxTurns: 200, hardMinTurns: 5 },
+      notes: [],
+      strict: false,
+    });
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    runAgent.mockResolvedValue([
+      { steps: [{ result: 'SUCCESS: ok' }], status: 'passed' },
+    ]);
+
+    await runMissions({ mission: 'No warnings' }, 'Clean');
+
+    expect(warn).not.toHaveBeenCalled();
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20);
+
+    warn.mockRestore();
+    log.mockRestore();
+  });
+
+  it('marks first mission failed when last step result includes "failure"', async () => {
+    loadConfig.mockResolvedValue({});
+    enforceTurnBudget.mockReturnValue({
+      effectiveMax: 20,
+      limits: {},
+      notes: [],
+      strict: false,
+    });
+
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    runAgent.mockResolvedValue([
+      { steps: [{ result: 'FAILURE: could not do it' }], status: 'passed' },
+    ]);
+
+    const res = await runMissions({ mission: 'Will fail' }, 'Status');
+    expect(res[0].status).toBe('failed');
+
+    log.mockRestore();
+  });
+
+  it('normalizes single strings and functions into arrays and names missions', async () => {
+    loadConfig.mockResolvedValue({});
+    enforceTurnBudget.mockReturnValue({
+      effectiveMax: 15,
+      limits: {},
+      notes: [],
+      strict: false,
+    });
+
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    runAgent.mockResolvedValue([
+      { steps: [{ result: 'SUCCESS: done' }], status: 'passed' },
+    ]);
+
+    function preTask() {}
+    function postTask() {}
+
+    await runMissions(
+      {
+        preMission: preTask,
+        mission: 'Main mission text\nwith details',
+        postMission: postTask,
+      },
+      'My Mission'
+    );
+
+    // Check that runAgent got 3 goals (pre/main/post)
+    const call = (runAgent.mock.calls[0] || []);
+    const goals = call[0];
+    expect(Array.isArray(goals)).toBe(true);
+    expect(goals).toHaveLength(3);
+
+    // Submission types and names are set
+    expect(goals[0].submissionType).toBe('premission');
+    expect(goals[1].submissionType).toBe('mission');
+    expect(goals[2].submissionType).toBe('postmission');
+
+    // Mission name is the passed-in missionName for main
+    expect(goals[1].submissionName).toMatch(/^My Mission/);
+
+    // Effective max turns passed through
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15);
+
+    log.mockRestore();
+  });
+
+  it('aborts early when runAgent returns falsy (defensive)', async () => {
+    loadConfig.mockResolvedValue({});
+    enforceTurnBudget.mockReturnValue({
+      effectiveMax: 10,
+      limits: {},
+      notes: [],
+      strict: false,
+    });
+
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    runAgent.mockResolvedValue(null); // simulate unexpected falsy
+
+    const res = await runMissions({ mission: 'Edge case' }, 'Abort');
+    expect(res).toBeUndefined();
+
+    log.mockRestore();
+  });
+});