expect-cli: AI Agent Browser Testing CLI

Common errors

• Error: Playwright browsers are not installed. Please run `npx playwright install`

  cause The underlying Playwright dependency needs its browser binaries downloaded to function correctly.
  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`.

• Command not found: expect-cli

  cause `expect-cli` is not globally installed or `npx` cannot locate it in `node_modules`.
  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).

• Unsupported Node.js version. Requires Node.js >=18.

  cause The system's Node.js version is older than the minimum required by `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.

Warnings

• breaking 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.
  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.
• gotcha 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).
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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>`.

Install

• npm install expect-cli npm
• yarn add expect-cli yarn
• pnpm add expect-cli pnpm

Imports

• CLI Execution

  import { spawn } from 'child_process';
  spawn('npx', ['expect-cli', 'test'], { stdio: 'inherit' });

  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.
• Configuration Types
  wrong:

  import { ExpectCLIOptions } from 'expect-cli'; // Runtime import will likely be undefined

  correct:

  import type { ExpectCLIOptions } from 'expect-cli';

  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.
• Generic Module Import
  wrong:

  import * as ExpectCLI from 'expect-cli'; // Will likely result in an empty object or error if no main export

  correct:

  // Primary interaction is via CLI, no direct module import for execution.

  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'.

Quickstart

Demonstrates how to programmatically initialize expect-cli for a project using Node.js's child_process module, specifying an AI agent.

import { spawn } from 'child_process';

const agentName = process.env.EXPECT_AGENT_NAME ?? 'claude'; // Example agent
const projectPath = './my-project'; // Path to your project

console.log(`Initializing expect-cli in ${projectPath} with agent: ${agentName}...`);

const initProcess = spawn('npx', [
  'expect-cli@latest',
  'init',
  '--agent', agentName,
  projectPath // Or other initialization parameters
], {
  stdio: 'inherit', // Pipe child process stdio to parent process
  cwd: process.cwd() // Run from current working directory
});

initProcess.on('error', (err) => {
  console.error('Failed to start expect-cli init process:', err);
});

initProcess.on('close', (code) => {
  if (code === 0) {
    console.log('expect-cli initialization completed successfully.');
    console.log(`
Now, try running: npx expect-cli@latest test ${projectPath}`);
  } else {
    console.error(`expect-cli init process exited with code ${code}`);
  }
});