expect-cli

library0.1.3jsnpmunverified

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.

testing ai-ml llm-agents web-framework devops

npm install expect-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPECT-CLI

expect-cli

testingjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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

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

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

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

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

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

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}`); } });

expect-cli --version

Debug

Known issues

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

affects: <1.0.0

gotchaexpect-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`.

affects: >=0.0.1

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

affects: >=0.0.1

gotchaexpect-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>`.

affects: >=0.0.1

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

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

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/millionco/expect ↗

packagehttps://www.npmjs.com/package/expect-cli ↗

homepagehttps://expect.dev ↗