Package Exports

qa-agent
qa-agent/dist/server.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (qa-agent) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

QA Agent

npm license build

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.