Skip to content

Config ​

ts
import { Monkey, autoLLMConfig } from '@monkeytestai/monkeytester';

const monkey = new Monkey({
  llm: autoLLMConfig({ quality: 'balanced' }),
});

Three surfaces: the Monkey constructor, the options on executeAndTriage, and environment variables. monkeytest init writes .monkeytest/config.json. The CLI does not load that file. Delete it, or keep it as notes. Its $schema URL is not a published JSON Schema.

Quality ​

qualityExplorerPlannerRunner
cheapcheapcheapcheap
balanced (default)cheapsmartcheap
smartsmartsmartsmart
ts
autoLLMConfig({
  quality: 'balanced',
  overrides: { runner: { provider: 'groq', model: 'llama-3.3-70b-versatile' } },
});

Omit runner and the planner model is reused for runner calls. Omit triager and triage stays deterministic. Model ids are on LLM providers.

LLMConfig is { provider, model?, apiKey?, baseURL?, temperature? }. temperature defaults to 0.2 for JSON calls. Models that reject a custom temperature (gpt-5*, o-series) omit the field, and a 400 that says temperature is unsupported is retried once without it. provider is openai, gemini, anthropic, mistral, groq, or openai_compatible. Do not select gpt-4.1-nano. It is deprecated. estimateCostUsd prices each step at that step's model. gpt-5-mini and gpt-5-nano have price rows.

executeAndTriage ​

ts
const { siteMap, plan, run } = await monkey.executeAndTriage(url, {
  explore: { maxPages: 6, screenshotsDir: '.monkeytest/shots' },
  plan: { maxFlows: 5 },
  run: { screenshotsDir: '.monkeytest/shots', headless: true },
});

Explore ​

OptionDefaultMeaning
maxPages8Crawl cap. Quick pass sets 6.
pageTimeoutMs20000Per-page navigation. Quick pass sets 12000.
headlesstrue
screenshotsDirViewport PNG per page, stored on the page
onPageCalled with each crawled page

Plan ​

OptionDefaultMeaning
maxFlows6LLM flow cap. Quick pass sets 5.
includeAuthFlowstrueKeep flows the model tagged auth_required
focusforms-search-cta on Quick pass
signupInboxfalsePlan exactly one sign-up when a sign-up form was crawled. true on its own does not submit. Pass inbox as well.

Run ​

OptionDefaultMeaning
screenshotsDirrequiredStep PNGs and per-flow WebM
stepTimeoutMs15000Quick pass sets 10000
flowTimeoutMs180000Quick pass sets 25000
headlesstrue
strictOracleson via new Monkey()Page error, document HTTP 404, action HTTP ≥500, or a disabled control fails the step
failOn5xxon via new Monkey()A same-origin HTTP ≥500 on document, xhr, or fetch fails the step
inboxInboxProvider. Allows the one sign-up, plus OTP and password-reset submits.
allowSensitiveExtra final submits: newsletter, payment, deletion. signup, reset, and otp are already allowed when inbox is set. Contact, enquiry, feedback, support, quote, and get-in-touch submits are never allowed.

runPlan, replayTraces, and a direct triage(run) leave strictOracles and failOn5xx off unless the caller passes them. new Monkey() turns both on and passes them through.

Depth presets are resolveDepthPreset('basic' | 'standard' | 'deep' | 'shallow') and BASIC_PRESET. CLI flags for the same knobs are in the CLI reference.

Environment ​

VariablePurpose
OPENAI_API_KEYOpenAI
OPENAI_MODELOptional default OpenAI model id
GEMINI_API_KEY / GOOGLE_API_KEYGemini
ANTHROPIC_API_KEYAnthropic
MISTRAL_API_KEYMistral
GROQ_API_KEYGroq
OPENAI_COMPATIBLE_BASE_URLOpenAI-compatible server
OPENAI_COMPATIBLE_API_KEYKey for that server
PLAYWRIGHT_BROWSERS_PATHChromium location
MONKEYTEST_INBOX_TOKENBearer token for --inbox-http
MONKEYTEST_DEBUGStack traces
MTAI_EGRESS_PROXYProxy URL for hosted sign-in. egressProxy on the call wins.
MTAI_ALLOW_HOSTED_AUTH_WITHOUT_PROXYtrue or 1 (any case) lets hosted sign-in run with no proxy. allowHostedAuthWithoutProxy on the call wins, including false. Other values are ignored.

Sign-up configuration is Sign-up testing. new Monkey({ inbox }) is the library form of --inbox.

AGPL-3.0-only