Supercharge Your Playwright automation by AI

Muon is a coding agent and an AI-powered test management tool by Autify built specifically for Playwright test automation. It enhances the development and maintenance of automated tests by introducing smart test generation, AI-driven debugging, and natural language-based dynamic test writing.

Getting Started

System Requirements

• NodeJS version 20 or higher

Installation

Register an account at Muon page and subscribe to free plan:

https://muon.autify.com

Install Muon globally using npm:

npm install -g @autifyhq/muon

Authentication

Option 1: OAuth Authentication (Recommended)

muon login

Option 2: API Key

1. Retrieve your API key from: https://muon.autify.com/keys
2. Set the environment variable:

export MUON_API_KEY=your_api_key_here

Check Authentication Status

muon status

Features

Agentic Playwright Code Generation ****

Generating Playwright code with Muon Agent, that follows your coding standards, including a language of your choice (JavaScript, TypeScript, Python, or .NET), Page Object Model, etc. When the UIs are very dynamic, using --nlstep option explained below would be recommended.

Command: (Run this command in your project root)

muon

Agentic Test Maintenance

• Automatically detects and fixes test failures.
• Applies multiple fix strategies, including selector updates and retry logic.
• Identifies root causes such as timing issues or missing elements.
• Runs in an interactive terminal-based chat session.

Test Management Features

• Launch interactive test sessions via CLI.
• Run tests directly from your project directory.
• Generate various test scenarios covering edge cases for both static and dynamic applications.

[Experimental] Handle Complex UI using Natural Language

This feature is provided via @autifyhq/muon-sdk , which currently supports only JavaScript and TypeScript. Please visit here to get started with your project.

The SDK offers you to write a natural language step between normal Playwright code. Here is an example of the usage.

import { test, expect } from '@playwright/test';
import { ai } from '@autifyhq/muon-sdk';

test('AI-powered login flow', async ({ page }) => {
  await page.goto('https://example.com/login');
  
  const result = await ai(
    'Fill in username "testuser", password "password123", then click login button',
    page
  );
  
});

This decides actions to take on the fly; therefore, it can be useful for fast-changing UI or very dynamic UI (like Calendar). This is still experimental, so please give us your feedback.

—-nlstep mode

When you add --nlstep option to muon start command, the Muon agent will automatically leverage the SDK to generate and execute steps more intelligently.

Command:

muon --nlstep

Or:

muon --nlstep

Advanced Features

• Dynamic Locator Mapping in with —-nlstep flag.
• Smart Selector Updates.
• Auto-Retry Logic for flaky tests.

MCP Integration

Muon CLI supports Model Context Protocol (MCP) integration, allowing you to connect to MCP servers for enhanced functionality.

MCP Commands

# Configure MCP servers (opens config file in editor)
muon mcp config

# List configured MCP servers
muon mcp list

# Validate MCP configuration
muon mcp validate

# Enable/disable MCP servers
muon mcp enable <serverName>
muon mcp disable <serverName>

# Add MCP servers
# stdio: provide command and optional args
muon mcp add <serverName> <command> [args...]

# SSE: provide URL
muon mcp add <serverName> --transport sse <url>

# HTTP (streamable-http): provide URL
muon mcp add <serverName> --transport http <url>

# Optional: add as disabled
muon mcp add <serverName> ... --disabled

MCP Configuration

The MCP configuration is stored in ~/.muon/mcp-config.json. For sse/http servers, you can use the following example configuration (using mcp-remote package):

{
  "mcpServers": {
      "jira-remote": {
         "transport": "stdio",
         "command": "npx",
         "args": [
         "-y",
         "mcp-remote",
         "https://mcp.atlassian.com/v1/sse"
         ],
         "enabled": true
      }
  }
}

You can add more MCP servers using the CLI (muon mcp add ...) or by editing the configuration file with muon mcp config.

Project Rules

Muon supports project-specific rules that allow you to customize the AI agent's behavior for your specific project needs. This feature enables consistent testing standards and project-specific guidelines across your team.

How to Use Project Rules

Create a .muon folder in your project root directoryAdd a rules.md file inside the .muon folderWrite your project-specific rules in Markdown formatStart Muon - the agent will automatically read and apply your rules

• Create a .muon folder in your project root directory
• Add a rules.md file inside the .muon folder
• Write your project-specific rules in Markdown format
• Start Muon - the agent will automatically read and apply your rules

File Structure

your-project/
├── .muon/
│   └── rules.md          # Your project rules
├── src/
├── tests/
├── package.json
└── ...

Example rules.md Content

**# Project-Specific Rules## Testing Standards**- Always use `data-testid` attributes when available
- Prefer semantic selectors over CSS classes
- Use descriptive test names

**## Code Style**- Follow existing code formatting patterns
- Use TypeScript for all new test files
- Implement Page Object Model pattern

**## Browser Configuration**- Set viewport to 1920x1080
- Use headless mode for CI/CD
- Enable video recording for failed tests

Benefits

• Consistent Testing Standards: Ensure all team members follow the same testing practices
• Project-Specific Guidelines: Customize the agent's behavior for your project's needs

CLI & API Reference

Commands

• muon: Start Muon agent.
  • -k <key>, --api-key <key>: Override API key (can be used instead of env var)
  • 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
  • m, --model <model> - Choose AI model (e.g., gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, claude-sonnet-4, gemini-2.5-pro)
  • -no-streaming - Disable streaming mode and use normal HTTP requests (default: streaming enabled)
  • -vim - Enable vim mode for this session
• muon login: Authenticate with Muon using OAuth device flow.
  • 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.
• muon update: Update Muon CLI to the latest version. The CLI will automatically check for updates when you run muon start and notify you if a new version is available.
• muon config: Manage Muon configuration settings.

Vim Mode

Muon supports vim-style input editing for users familiar with vim keybindings.

Enabling Vim Mode muon --vim

Note: Vim mode is only enabled for the current session when using the --vim flag. It is not persisted between sessions.

Troubleshooting and Debugging

Authentication Issues

• Check login status

muon status

• Verify login:

muon login

• Check API key:

echo $MUON_API_KEY

• Visit the key dashboard: https://muon.autify.com/keys
• Check if your subscription is active at https://muon.autify.com

Mode Selection Issues

• Use muonfor traditional tests.
• Use muon —-nlstep for generate natural-language-based tests with @autifyhq/muon-sdk.
• Ensure @autifyhq/muon-sdk is installed in your target project for —-nlstep flag to function correctly.

Try It Yourself

Target Website: https://autifyhq.github.io/genesis-sample-app-mobile-carrier-plan-simulator/

Launch the Muon agent in your terminal using muon and then paste the below text.

Execute the below scenario using browser and write a playwright code for the same:

Feature: Mobile Service Plans – selecting maximum options with discounts

Target Site: https://autifyhq.github.io/genesis-sample-app-mobile-carrier-plan-simulator/

Scenario: User selects unlimited talk, highest data, all discounts, and relevant options
   * Given the user is on the “Mobile Service Plans” page
   * When the user selects “Infinity Talk Max” under Basic Talk Plans (Unlimited domestic calls, $32/month)
   * And the user selects “Data Titan 50” under Data Plans → Fixed Allowance (50 GB, $50/month)
   * And the user selects the contract term “3 Years - $7/month discount for 24 months”
   * And the user checks “Switching from another carrier - $4/month discount for 12 months”
   * And the user checks “Peace-of-Mind Pack” ($7/month)
   * And the user checks “Data Rollover” (Free)
   * Then the Plan Summary shows a breakdown including:
       * Internet Access Fee $2
       * Infinity Talk Max $32
       * Data Titan 50 $50
       * Peace-of-Mind Pack $7
       * Contract discount -$7 (24 months)
       * MNP discount -$4 (12 months)
   * And the Monthly Total before tax is $80
     (Calculation: 32 + 50 + 2 + 7 − 7 − 4 = 80)

The muon agent will launch the browser and create a PW script to test the scenario.

FAQ

• When should I use nlstep mode?

  Use it when dealing with complex UI layouts or elements without stable attributes.

• Can Muon auto-fix failing tests?

  Yes. In standard mode, Muon uses AI to suggest and apply fixes for failing test steps.

• What if I don’t have stable selectors?

  Use nlstep mode with natural language inputs. Muon uses intelligent heuristics to find elements dynamically.

Support and Contact

• Web: https://muon.autify.com/
• API Keys & Subscription: https://muon.autify.com/keys
• Support: You can also send an email to [email protected] for queries related to muon