@autifyhq/muon-sdk

AI-powered Playwright agent for writing end-to-end tests in natural language. You describe what to do; the agent operates the browser via Playwright.

What it does

The SDK connects your Playwright test to a Muon server. The server interprets your instruction and returns a sequence of tool calls (like running Playwright code, evaluating JavaScript, reading DOM) that the SDK executes on your page.

Requirements

• Node.js >= 24.4.1
• Playwright >= 1.50.0 (and browsers installed)

Install Playwright if you don't have it yet:

npm i -D playwright @playwright/test
npx playwright install

Install the SDK

npm i @autifyhq/muon-sdk

Configure environment

Export these variables (e.g., in your shell, CI, or a dotenv setup):

# Required: Muon server API key (sent as x-muon-api-key)
export MUON_API_KEY=your_api_key_here

# Optional (default: https://muon.autify.com)
export MUON_SERVER_URL=https://your-muon-server.com

# Optional: disable caching (enabled by default)
# Any of: 1/true/yes/on => disabled
export MUON_CACHE_DISABLED=1

Notes:

• When MUON_SERVER_URL is omitted, the SDK uses https://muon.autify.com.
• Cache files are stored under .muon/nlstep-cache/ in your project.

Quickstart

Use the ai step inside a Playwright test. It automatically wraps your action as a Playwright test.step using the task text (or a custom stepName). The function automatically fails the test if the AI task is unsuccessful.

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

test('AI-powered login', async ({ page }) => {
  await page.goto('https://example.com/login');

  await ai({
    task: 'Fill username "testuser", password "password123", then click "Log in"',
    page,
    timeout: 60_000,      // optional (default 180000)
    maxSteps: 50,         // optional (default 50)
    stepName: 'Login via AI', // optional
  });
});

Notes:

• You can also call ai with positional parameters in the original order if you prefer.
• If the AI task fails, the test automatically fails with detailed error information.

Caching

The agent caches successful tool call sequences to speed up repeat runs under similar conditions (task, URL, viewport, test title). Files are stored at .muon/nlstep-cache/.

• Leave caching enabled by default for faster CI.
• Disable globally by setting MUON_CACHE_DISABLED to any of: 1, true, yes, on (case-insensitive).
• To clear, delete .muon/nlstep-cache/.

Troubleshooting

• Missing API key: The SDK throws a clear error: missing MUON_API_KEY with reason and how to set it.
• Invalid server URL: The SDK validates MUON_SERVER_URL and explains the reason if invalid.
• Connection errors: The SDK surfaces network/connectivity reasons and hints (check reachability, proxy, TLS, DNS).
• Long/unstable pages: Increase timeoutMs or allow more maxSteps.
• Flaky runs with iframes or dynamic DOM: The agent gathers DOM and iframe snapshots but you can give more precise instructions (e.g., name the button text) to stabilize.

Example: robust submit step

await test.step('Submit via AI', async () => {
  await ai({ task: 'Click the primary "Submit" button and wait for confirmation', page, timeout: 90000, maxSteps: 80, stepName: 'Submit via AI' });
});