@withkeystone/cli/README.md

Keystone CLI - Test automation for modern web apps

# Keystone Local Runner

Run Keystone tests locally against your localhost applications with visual test recording.

## Installation

```bash
npm install -g @withkeystone/cli
```

## Usage

Start the local runner:

```bash
keystone start
```

Options:
- `-p, --port <port>` - WebSocket port (default: 9223)
- `--headless` - Run browser in headless mode
- `--debug` - Enable debug logging

## How it works

1. The local runner starts a WebSocket server on port 9223
2. When you open Keystone Studio and enter a localhost URL, it automatically detects the local runner
3. Your localhost app is embedded in an iframe alongside the test builder
4. You can record actions by clicking the "Record Actions" button
5. Recorded actions are automatically converted to test steps

## Requirements

- Chrome or Chromium browser installed
- Node.js 16+

## Features

- **Visual Recording**: Click "Record Actions" to automatically capture clicks, typing, and form submissions
- **Real-time Execution**: Run test steps instantly against your local app
- **Network Capture**: Monitor all network requests during test execution
- **Screenshot Support**: Capture screenshots before and after each step

## Limitations

- Recording only works for same-origin pages (localhost)
- Cross-origin sites require proxy mode (coming soon)

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js start
```