Recipes
Copy-paste patterns. Adjust the URL, the caps, and the model.
Test a deploy preview, fail the build on bugs
import { Monkey, autoLLMConfig } from '@monkeytestai/monkeytester';
const monkey = new Monkey({ llm: autoLLMConfig({ quality: 'balanced' }) });
const { run } = await monkey.executeAndTriage(process.env.PREVIEW_URL!, {
explore: { maxPages: 6, screenshotsDir: '.monkeytest/shots' },
plan: { maxFlows: 4 },
run: { screenshotsDir: '.monkeytest/shots', headless: true },
});
const blocking = run.bugs.filter(b => b.severity !== 'minor');
if (blocking.length){
console.error(`Found ${blocking.length} blocking bugs:`);
for (const b of blocking) console.error(`- [${b.severity}] ${b.title}`);
process.exit(1);
}Persist a run to disk and diff it later
import { writeFileSync } from 'node:fs';
const result = await monkey.executeAndTriage(url, { explore: ..., plan: ..., run: ... });
writeFileSync(
`runs/${new Date().toISOString()}.json`,
JSON.stringify({ siteMap: result.siteMap, plan: result.plan, run: result.run }, null, 2),
);Bug fingerprints are stable across runs, so you can diff bugs[].fingerprint between two runs to know what's new, fixed, or regressed.
Live progress in your CLI
import { Monkey, EventBus, autoLLMConfig } from '@monkeytestai/monkeytester';
const events = new EventBus();
events.on(e => {
const tag = `[${e.phase}/${e.type}]`.padEnd(28);
console.log(`${new Date(e.ts).toLocaleTimeString()} ${tag} ${e.message}`);
});
await new Monkey({ llm: autoLLMConfig() }).executeAndTriage(url, {
events,
explore: { maxPages: 8, screenshotsDir: '.monkeytest/shots' },
plan: { maxFlows: 4 },
run: { screenshotsDir: '.monkeytest/shots' },
});Stream live progress over SSE
import express from 'express';
import { EventBus } from '@monkeytestai/monkeytester';
const app = express();
const buses = new Map<string, EventBus>();
app.get('/runs/:id/stream', (req, res) => {
res.set({ 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
const bus = buses.get(req.params.id);
if (!bus) return res.end();
const off = bus.on(evt => res.write(`data: ${JSON.stringify(evt)}\n\n`));
req.on('close', off);
});Headed mode (watch the monkey work)
Helpful when debugging selectors or auth flows.
await monkey.executeAndTriage(url, {
explore: { maxPages: 4, headless: false, screenshotsDir },
plan: { maxFlows: 2 },
run: { screenshotsDir, headless: false },
});Cheap local dev with Ollama
import { Monkey } from '@monkeytestai/monkeytester';
const monkey = new Monkey({
llm: {
explorer: { provider: 'openai_compatible', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama', model: 'llama3.1:8b' },
planner: { provider: 'openai_compatible', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama', model: 'llama3.1:70b' },
runner: { provider: 'openai_compatible', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama', model: 'llama3.1:8b' },
},
});Polished bug reports for production runs
Add a cheap triager LLM and the engine rewrites every bug's copy after the deterministic pass. Per-bug try/catch — failures keep the rule-based copy.
new Monkey({
llm: {
explorer: { provider: 'gemini', model: 'gemini-flash-lite-latest' },
planner: { provider: 'anthropic', model: 'claude-sonnet-4-5' },
runner: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
triager: { provider: 'anthropic', model: 'claude-haiku-4-5' },
},
});See Triager polish for what changes and how to control cost.
Use Anthropic for the planner only
The single best price/quality lever:
new Monkey({
llm: {
explorer: { provider: 'gemini', model: 'gemini-flash-lite-latest' },
planner: { provider: 'anthropic', model: 'claude-sonnet-4-5' },
runner: { provider: 'gemini', model: 'gemini-flash-lite-latest' },
},
});Test only specific user journeys
The library doesn't (yet) accept a hand-written plan, but you can pass a deeper start URL so the planner focuses on a specific area:
await monkey.executeAndTriage('https://app.example.com/checkout', {
explore: { maxPages: 4, screenshotsDir },
plan: { maxFlows: 3, includeAuthFlows: false },
run: { screenshotsDir, headless: true },
});Drive it from your own agent
The package is a library. Import it. Read the stored run. There is no MCP server and no hosted REST API in this repository.
saveRun writes schema 1 (RUN_FILE_SCHEMA). run is a RunResult. The field list is the report reference. Agents should treat outcome inconclusive and could_not_test as unfinished, not as a pass, and should not send contact or other sensitive submits the engine blocked.
import { Monkey, autoLLMConfig, saveRun, loadRun, diffRuns } from '@monkeytestai/monkeytester';
const monkey = new Monkey({ llm: autoLLMConfig({ quality: 'balanced' }) });
const { plan, run } = await monkey.executeAndTriage(process.env.PREVIEW_URL!, {
explore: { maxPages: 6, screenshotsDir: '.monkeytest/shots' },
plan: { maxFlows: 5 },
run: { screenshotsDir: '.monkeytest/shots', headless: true },
});
const saved = saveRun(run, { dir: '.monkeytest' });
console.log(saved.id, run.outcome, run.bugs.length);Accuracy comes before a wider agent surface. The fixed 10-site gate has not been measured. See Quality methodology.
Embed in your own product
The snippets below wrap the same library in a process you operate. They do not turn monkeytester into a hosted API.
The package is ESM, fully typed, and has zero opinionated dependencies on a host framework. Wrap it in a worker, an API route, a Tauri app, a VS Code extension — wherever.
// worker/runMonkey.ts
import { Monkey, autoLLMConfig, EventBus } from '@monkeytestai/monkeytester';
export async function runMonkeyTest({ url, screenshotsDir, onEvent }) {
const events = new EventBus();
events.on(onEvent);
const monkey = new Monkey({ llm: autoLLMConfig({ quality: 'balanced' }) });
return monkey.executeAndTriage(url, {
events,
explore: { maxPages: 8, screenshotsDir },
plan: { maxFlows: 4 },
run: { screenshotsDir, headless: true },
});
}Next: Use in CI →