Installation

@monkeytestai/monkeytester 0.5.1 is published on npm. npm install @monkeytestai/monkeytester is the install. A clone is the path for contributors.

Requirements

• Node.js 20+ (node -v). The engine is native ESM and uses node: builtins.
• Playwright Chromium, downloaded once with npx playwright install chromium (about 170 MB for current builds, plus a headless shell).
• An LLM API key only when you want a real crawl-plan-run. The smoke script in the quick start uses a stub LLM and needs no key.

npm

npm

npm install @monkeytestai/monkeytester
npx playwright install chromium

pnpm

pnpm add @monkeytestai/monkeytester
pnpm exec playwright install chromium

yarn

yarn add @monkeytestai/monkeytester
yarn playwright install chromium

bun

bun add @monkeytestai/monkeytester
bunx playwright install chromium

The package is ESM, ships TypeScript declarations, and exposes a monkeytest binary (npx monkeytest, or monkeytest after a global install). Releases are published from .github/workflows/release.yml on a v* tag, with npm provenance.

From a clone (contributors)

The clone is how you change the engine. It also runs the no-key smoke script, which is not in the published package.

git clone https://github.com/monkeytestai/monkeytester.git
cd monkeytester
npm install
npm run build
npx playwright install chromium
node scripts/smoke.mjs

npm run build writes dist/, including dist/cli.js. Run the CLI with node dist/cli.js. Step-by-step output, the Gemini command, and Ollama are on the quick start.

npm run build removes .tsbuildinfo before tsc, and TypeScript incremental mode is off. A fresh build emits .js and .d.ts. If you are on an older commit and dist/ contains only declaration files, run npm run clean && npm run build.

Set up a provider when you want a real run

Auto-detect walks this list and uses the first one that is set:

Variable	Provider	Key
GEMINI_API_KEY or GOOGLE_API_KEY	Google Gemini	https://aistudio.google.com/apikey
OPENAI_API_KEY	OpenAI	https://platform.openai.com/api-keys
ANTHROPIC_API_KEY	Anthropic Claude	https://console.anthropic.com/settings/keys
MISTRAL_API_KEY	Mistral	https://console.mistral.ai/api-keys/
GROQ_API_KEY	Groq	https://console.groq.com/keys
OPENAI_COMPATIBLE_BASE_URL	Ollama, vLLM, LM Studio, OpenRouter, …	The base URL. OPENAI_COMPATIBLE_API_KEY is optional for local servers

A missing variable fails immediately (exit 2), before Chromium launches. A variable that is set to a rejected key fails later, after the crawl, with the provider's raw error (exit 3). Both cases are in Troubleshooting.

export GEMINI_API_KEY="paste-your-key"
npx monkeytest run https://example.com --max 2 --flows 1

From a clone, the same command is node dist/cli.js run https://example.com --max 2 --flows 1.

Outputs land in .monkeytest/plan.json, .monkeytest/runs/, and .monkeytest/shots/. The copy-paste Ollama block is on the quick start.

Next: Quick start →