@autifyhq/muon/README.md

Muon - AI-Powered Playwright Test Coding Agent with Advanced Test Fixing Capabilities

# Muon - AI-Powered Playwright Test Coding Agent

Muon is an AI-powered test management and coding agent specialized in Playwright test automation. It features advanced AI-powered test fixing capabilities with an **experimental NL step feature** (using `--nlstep` flag) for complex/dynamic locators with `@autifyhq/muon-sdk`.

## 📦 Installation

### From npm (Recommended)

```bash
npm install -g @autifyhq/muon
```

## 🚀 Quick Start

### Prerequisites

- Node.js 20+
- Sign up for an account at [https://muon.autify.com](https://muon.autify.com)

### Authentication

#### Option 1: OAuth Authentication (Recommended)

```bash
muon login
```

#### Option 2: API Key

1. Get your API key from [https://muon.autify.com/keys](https://muon.autify.com/keys)
2. Set the environment variable:

   ```bash
   export MUON_API_KEY=your_api_key_here
   ```

### Check Authentication Status

```bash
muon status
```

## 🎯 Usage

### Standard Usage

For general Playwright code generation:

```bash
# Start interactive chat
muon start /path/to/your/project

# Or for current directory
muon start .

```

### With Experimental NL Step Feature

For complex/dynamic locators using `@autifyhq/muon-sdk`, enable the experimental flag:

```bash
# Enable experimental NL step feature for dynamic content
muon start --nlstep /path/to/your/project

# Or for current directory
muon start --nlstep .

```

## 📋 Available Commands

### `muon start [projectPath]`

Start Muon AI Test Agent with interactive terminal UI for test management.

**Options:**

- `-s, --server-url <url>` - Server URL (default: <https://muon.autify.com>)
- `-k, --api-key <key>` - API key (overrides MUON_API_KEY environment variable)
- `--nlstep` - (Experimental) Enable natural language step feature for complex/dynamic locators

### `muon login`

Authenticate with Muon using OAuth device flow.

**Options:**

- `-s, --server-url <url>` - Server URL (default: <https://muon.autify.com>)

### `muon logout`

Sign out from Muon and clear stored tokens.

### `muon status`

Check current authentication status and token validity.

## 🌟 Key Features

### Core Features

- 🧠 **AI-Powered Test Fixing** - Automatically analyze and fix failing tests
- 🌐 **Browser Simulation** - Real browser testing and validation
- 🎯 **Smart Selector Updates** - Auto-update outdated CSS selectors
- 🔄 **Auto-Retry Logic** - Multiple fix strategies until tests pass
- 📊 **Root Cause Detection** - Identify timing and element issues
- 💬 **Interactive Chat** - Ongoing test management sessions

### Experimental NL Step Feature (--nlstep)

The agent can generate natural language steps for complex/dynamic locators using `@autifyhq/muon-sdk`.

- 🚀 **Natural Language Steps** - Complex interactions using plain English
- 🎯 **Dynamic Locator Handling** - Works with changing UI elements
- 🔄 **Intelligent Caching** - Cached responses for repeated interactions

## 🛠️ When to Use the Experimental NL Step Feature

### Use Standard Mode (without --nlstep) for

- Simple, stable elements with clear attributes (id, data-testid, role)
- Static content that doesn't change frequently
- Elements with predictable structure
- Traditional Playwright test development

### Enable Experimental NL Step Feature (--nlstep) for

- Complex dynamic content (dashboards, feeds, changing layouts)
- Elements without stable selectors
- Multi-step interactions requiring contextual understanding
- Forms with conditional fields or dynamic validation

## 🚨 Troubleshooting

### Authentication Issues

1. **Check authentication status:**

   ```bash
   muon status
   ```

2. **Try logging in again:**

   ```bash
   muon login
   ```

3. **For API key issues:**

   ```bash
   # Check if API key is set
   echo $MUON_API_KEY
   
   # Get a new key from the dashboard
   open https://muon.autify.com/keys
   ```

4. **Verify subscription is active** at [https://muon.autify.com](https://muon.autify.com)

### Feature Selection Issues

- Use `muon start` for standard Playwright testing
- Use `muon start --nlstep` when working with dynamic/complex UI elements (experimental feature)
- Check that `@autifyhq/muon-sdk` is installed when using the --nlstep flag