SiteSpector is an innovative multi-agent system 🤖 designed to automatically explore, scan, and perform quality assurance (QA) tests on any website. Leveraging the power of Large Language Models (LLMs), it simulates human-like interaction to identify potential UI anomalies and generate comprehensive reports. ✨

SiteSpector operates through the collaboration of four specialized LLM-driven agents:

1. 📝 Task Planner Agent: Analyzes web pages and intelligently generates exploration and testing tasks for other agents.
2. 🧭 Explore Agent: Receives tasks from the Planner and automatically executes them, navigating the website like a user.
3. 🧐 Quality Assessment (QA) Agent: Scrutinizes each page visited by the Explore Agent, performing QA checks to identify potential UI issues or anomalies.
4. 📊 Report Agent: Consolidates all findings from the exploration and QA phases into a structured, professional test report.

• 🚀 High Concurrency: Run hundreds or even thousands of agents simultaneously to scan and test large websites rapidly.
• 🗺️ Efficient Exploration: Utilizes a directed graph to track visited pages and navigation paths, preventing redundant exploration and ensuring comprehensive coverage.
• 🤖 LLM-Powered Intelligence: Agents leverage advanced LLMs for task generation, execution, and assessment, enabling sophisticated testing scenarios.
• 📄 Automated Reporting: Generates detailed reports summarizing test coverage, identified issues, and overall site quality.

Follow these steps to get SiteSpector up and running:

1. Prerequisites: Redis 💾

SiteSpector requires a Redis instance (specifically Redis Stack for certain features). If you're running locally, Docker is the easiest way:

docker run -d --name site-spector-redis -p 6379:6379 \
    -e REDIS_ARGS="--appendonly yes --appendfsync everysec" \
    --restart=always redis/redis-stack:latest

2. Install Project Dependencies 📦

You'll need git and uv (a fast Python package installer and manager).

# Clone the repository
git clone https://github.com/vvincent1234/site-spector
cd site-spector

# Install dependencies using uv
uv sync

# Install Playwright browsers
uv run playwright install

3. Configure Environment Variables ⚙️

Copy the example environment file and fill in your details:

cp .env.example .env

Now, edit the .env file with your specific configuration. Crucially, you need to add your API keys for the LLM providers.

# redis
REDIS_HOST=localhost
REDIS_PORT=6379

# === Agent settings ===
# Make sure to replace 'your_api_key_here' with your actual keys!

# QA Agent
qa_provider=openai
qa_model_name=gpt-4o
qa_base_url=https://api.openai.com/v1
qa_api_key=your_api_key_here # ⚠️ Add your OpenAI key

# Planner Agent
plan_provider=openai
plan_model_name=gpt-4o
plan_base_url=https://api.openai.com/v1
plan_api_key=your_api_key_here # ⚠️ Add your OpenAI key

# Explorer Agent
explore_provider=openai
explore_model_name=gpt-4o
explore_base_url=https://api.openai.com/v1
explore_api_key=your_api_key_here # ⚠️ Add your OpenAI key

# Report Agent
report_provider=openai
report_model_name=gpt-4o
report_base_url=https://api.openai.com/v1
report_api_key=your_api_key_here # ⚠️ Add your OpenAI key

4. Run the Web UI ▶️

Start the SiteSpector web interface:

uv run app.py

Open your web browser and navigate to: http://127.0.0.1:7777 🌐

1. Access the Web UI at http://127.0.0.1:7777.
2. Enter the URL of the website you want to test in the input field.
3. Configure the key parameters:
   • Number of Agents: Set how many agents you want to run concurrently on your machine. More agents mean faster scanning but higher resource usage.
   • Max Task Number: Define the maximum number of tasks each individual agent should execute before stopping.
4. Click the "Run" button to start the scanning and testing process!
5. Monitor the progress and view the final report once the agents complete their tasks.

Happy Testing! 🎉