{"id":15324,"library":"expect-cli","title":"expect-cli: AI Agent Browser Testing CLI","description":"expect-cli is a command-line interface tool designed to enable AI agents to test web applications in a real browser environment. It leverages browser automation tools like Playwright to record user sessions, generate test plans, and perform diffing against expected outcomes, often integrating with version control systems like Git. The current stable version is 0.1.3. Given its low version number and frequent updates (as seen in the release logs), it appears to have a rapid, iterative release cadence. It differentiates itself by explicitly targeting AI agents for automated test generation and execution, moving beyond traditional script-based automation towards more autonomous, intelligent testing within a live browser context.","status":"active","version":"0.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/millionco/expect","tags":["javascript","agents","ai","browser-automation","cli","git-diff","playwright","session-recording","test-plan","typescript"],"install":[{"cmd":"npm install expect-cli","lang":"bash","label":"npm"},{"cmd":"yarn add expect-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add expect-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"expect-cli uses Playwright internally for browser automation. While not a direct dependency in package.json, its functionality relies on Playwright being available and correctly configured in the environment.","package":"playwright","optional":false}],"imports":[{"note":"expect-cli is primarily a command-line interface tool. Programmatic interaction typically involves spawning it as a child process, rather than importing specific functions as a library. The `npx` prefix ensures the locally installed version is used.","symbol":"CLI Execution","correct":"import { spawn } from 'child_process';\nspawn('npx', ['expect-cli', 'test'], { stdio: 'inherit' });"},{"note":"While expect-cli ships TypeScript types, runtime imports of configuration interfaces or helper types are not generally intended for direct execution. These types are primarily for enhancing developer experience during configuration or when extending expect-cli's capabilities through plugins or wrappers.","wrong":"import { ExpectCLIOptions } from 'expect-cli'; // Runtime import will likely be undefined","symbol":"Configuration Types","correct":"import type { ExpectCLIOptions } from 'expect-cli';"},{"note":"Attempting a wildcard or default import for expect-cli as a traditional JavaScript module is generally incorrect, as its main entry point is a CLI executable. The package is optimized for command-line usage and not designed for direct library-style programmatic calls within a Node.js application, unlike its associated 'expect-sdk'.","wrong":"import * as ExpectCLI from 'expect-cli'; // Will likely result in an empty object or error if no main export","symbol":"Generic Module Import","correct":"// Primary interaction is via CLI, no direct module import for execution."}],"quickstart":{"code":"import { spawn } from 'child_process';\n\nconst agentName = process.env.EXPECT_AGENT_NAME ?? 'claude'; // Example agent\nconst projectPath = './my-project'; // Path to your project\n\nconsole.log(`Initializing expect-cli in ${projectPath} with agent: ${agentName}...`);\n\nconst initProcess = spawn('npx', [\n  'expect-cli@latest',\n  'init',\n  '--agent', agentName,\n  projectPath // Or other initialization parameters\n], {\n  stdio: 'inherit', // Pipe child process stdio to parent process\n  cwd: process.cwd() // Run from current working directory\n});\n\ninitProcess.on('error', (err) => {\n  console.error('Failed to start expect-cli init process:', err);\n});\n\ninitProcess.on('close', (code) => {\n  if (code === 0) {\n    console.log('expect-cli initialization completed successfully.');\n    console.log(`\nNow, try running: npx expect-cli@latest test ${projectPath}`);\n  } else {\n    console.error(`expect-cli init process exited with code ${code}`);\n  }\n});","lang":"typescript","description":"Demonstrates how to programmatically initialize expect-cli for a project using Node.js's child_process module, specifying an AI agent."},"warnings":[{"fix":"Always refer to the latest documentation and release notes. Pin exact versions in your `package.json` to prevent unexpected updates, and test thoroughly after any version change.","message":"Due to its early development stage (version 0.1.3), expect-cli is subject to frequent breaking changes. APIs, CLI commands, and configuration options may change without major version bumps in accordance with semantic versioning pre-1.0.0 guidelines.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure your environment meets Playwright's system requirements. If issues arise, manually install Playwright browsers with `npx playwright install` or `npx playwright install --with-deps`.","message":"expect-cli relies on Playwright for browser automation, which requires specific browser binaries to be installed. These are typically installed automatically when Playwright is installed, but can sometimes lead to issues in constrained environments (e.g., CI/CD without necessary OS dependencies or sandboxing disabled).","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always specify `expect-cli` explicitly when installing or running (e.g., `npm install expect-cli`, `npx expect-cli`) to avoid conflicts or unintended installations.","message":"The name 'expect-cli' can be confused with other `expect` libraries (e.g., Jest's `expect` assertion library) or the older Tcl-based `expect` command-line utility for automating interactive processes. This `expect-cli` is specifically for AI-driven browser testing.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Verify that your desired AI agent is correctly installed and accessible on your system's PATH. Use `npx expect-cli --help` to see supported agents and ensure your agent is configured as per its documentation, or explicitly pass the agent with `-a <provider>`.","message":"expect-cli integrates with various AI coding agents (e.g., Claude Code, Codex, GitHub Copilot). Proper functioning requires one of these agents to be installed and configured on the system's PATH, or specified via the `--agent` flag. Misconfiguration or missing agents will prevent testing.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npx playwright install` in your project directory to download the necessary browser binaries for Playwright. For CI environments, consider `npx playwright install --with-deps`.","cause":"The underlying Playwright dependency needs its browser binaries downloaded to function correctly.","error":"Error: Playwright browsers are not installed. Please run `npx playwright install`"},{"fix":"If installed locally, run with `npx expect-cli <command>`. If you intend to use it globally, install with `npm install -g expect-cli` (though `npx` is generally recommended for local CLI tools).","cause":"`expect-cli` is not globally installed or `npx` cannot locate it in `node_modules`.","error":"Command not found: expect-cli"},{"fix":"Upgrade your Node.js environment to version 18 or newer. Use a tool like `nvm` (Node Version Manager) to easily manage and switch Node.js versions.","cause":"The system's Node.js version is older than the minimum required by `expect-cli`.","error":"Unsupported Node.js version. Requires Node.js >=18."}],"ecosystem":"npm"}