QA Agent

A powerful CLI tool that uses autonomous agents to crawl, analyse, and test the interactive components of any given website or web application. It's designed for developers and QA teams who want an automated assistant to navigate and evaluate webpages for interactivity, functionality, and structural issues. Check out the site at QA Agent for more detailed info and steps

🚀 Features

• Crawl and map internal website pages
• Detect and log interactive elements (buttons, forms, links)
• Automated testing of links and UI components
• Pluggable architecture with support for LLM analysis
• CLI-first design for easy integration into dev workflows

📦 Installation

You can install the package globally:

npm install -g qa-agent

🛠️ Usage

Run the agent with your desired configuration:

agent-run --goal "Test all interactive elements" --url https://example.com --key <GOOGLE_GENAI_API_KEY>

You can also use a config file instead of passing arguments:

agent-run --config ./agent.json

Example config file (agent.json):

{
  "goal": "Test the login functionality",
  "key": "your-api-key",
  "url": "http://localhost:3000",
  "port": 3001,
  "auto-start": true,
  "detailed": true,
  "headless": true,
  "endpoint": false,
  "data": {
    "additional": "info"
  }
}

⚙️ CLI Arguments

| Flag | Description | Required | Default | |------------------|-----------------------------------------------------------------------------|----------|---------| | --goal | Goal for the QA agent (what to test/achieve) | ✅ | - | | --url | Base URL of the site to test | ✅ | - | | --key | Google GenAI API Key | ✅ | - | | --port | Local server port | ❌ | 3001 | | --config, -c | Path to JSON config file | ❌ | - | | --auto-start | Automatically start the agent | ❌ | true | | --daemon, -d | Run in background (daemon mode) | ❌ | false | | --sessionId | Session identifier for multi-run tracking | ❌ | "1" | | --headless | Run browser in headless mode | ❌ | false | | --detailed | Test every UI element across all pages (more exhaustive, slower) | ❌ | false | | --endpoint | Run agent in API endpoint testing mode | ❌ | false | | --autoconnect | Automatically open the updates dashboard in the browser | ❌ | true | | --help, -h | Show help message | ❌ | - | | optimize-images| Optimize images. Lead to more accurate results but takes more time. | ❌ | false. | | cross-platform | The agent will test on desktop, mobile and tablet. | ❌ | false. |

📑 Logs & Monitoring

QA Agent stores logs in the logs/ directory of your project.

You can inspect logs directly from the CLI:

agent-run logs            # Show main log
agent-run logs --json     # Output logs in JSON format
agent-run mission         # Show mission log (markdown)
agent-run crawl-map       # Show crawl results (markdown)
agent-run navigation-tree # Show navigation tree (markdown)
agent-run logs-dir        # Show logs directory path

Each log may also be session-specific (e.g., crawl_map_1.md).

🧭 Subcommands

• agent-run run → Start the agent
• agent-run stop → Stop all running agents
• agent-run logs → View logs
• agent-run crawl-map → View crawl map
• agent-run mission → View mission log

🧪 Examples

Run with inline arguments:

agent-run --goal "Analyze UI usability" --url https://myapp.com --key ABC123

Run in daemon mode:

agent-run --goal "Test login" --url http://localhost:3000 --key ABC123 --daemon

Run with config file:

agent-run --config ./agent.json

Run in detailed mode (tests every button, form, and link):

agent-run --goal "Deep test of UI components" --url https://app.com --key ABC123 --detailed

📁 Project Structure

├── bin/                # CLI entry point
├── dist/               # Compiled agent logic, server, testing modules
├── logs/               # Session logs and results
├── package.json        # NPM metadata
└── README.md           # Project documentation

📄 License

This project is licensed under the Apache License. See the LICENSE file for details.