@autifyhq/muon

# 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](https://muon.autify.com) 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](https://muon.autify.dev/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](https://www.npmjs.com/package/@autifyhq/muon-sdk) 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. ```tsx 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)**](https://github.com/modelcontextprotocol) integration, allowing you to connect to MCP servers for enhanced functionality. **MCP Commands** ```bash # 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): ```bash { "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** ```markdown **# 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](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](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:](https://muon.autify.dev/)[//muon.autify.com](https://muon.autify.com/) ## **Mode Selection Issues** - Use `muon`for 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](https://muon.autify.dev/keys) - Support: You can also send an email to [muon-support@autify.com](mailto:muon-support@autify.com) for queries related to muon