Virtual Visitors

A configurable traffic simulation tool for development, testing, and performance validation.

⚠️ Ethical Use Notice: This tool is intended solely for testing websites you own or have explicit written permission to test. Do not use it to artificially inflate metrics, interfere with third-party services, or violate any terms of service.

Overview

Virtual Visitors simulates realistic browser-like requests to a target URL with configurable concurrency, session duration, and resource constraints. It is designed for:

• Testing analytics pipelines and event-tracking implementations
• Validating load balancer, CDN, or caching behavior under controlled traffic
• Stress-testing frontend performance in staging or pre-production environments
• Debugging session management, rate limiting, or bot-detection logic

All traffic is generated locally. Proxy support is provided for testing geo-routing or proxy-integration logic—not for anonymity or evasion.

Features

• Configurable visit count, duration, and concurrency
• RAM-aware scheduling with automatic safety limits
• Headless browser simulation (Selenium/Playwright backend)
• Optional proxy rotation for infrastructure testing
• Two operational modes:
  • BURST: Schedule N visits spread over a defined time window
  • STREAM: Maintain up to N concurrent simulated visitors

Requirements

• Python 3.8+
• Linux/macOS (for meminfo-based resource tracking)
• venv, selenium (or compatible browser driver)
• Webshare proxy account (optional, for proxy rotation testing)

Installation

# Clone and set up virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Generate default configuration
python setup.py

Configuration

Main Config (config/config.json)

Parameter	Type	Default	Description
min_visit_duration_secs	int	20	Minimum simulated session duration
max_visit_duration_secs	int	180	Maximum simulated session duration
max_active_visitors	int	2	Max concurrent visitors (STREAM mode)
ram_budget_fraction	float	0.3	Max fraction of system RAM the tool may use
peak_ram_usage_bytes	int	47411200	Estimated peak RAM per visitor (~45 MB)
scheduler_interval_secs	int	600	Time between scheduling windows
scheduler_lifetime_secs	int	84600	Total runtime before auto-shutdown (~23.5 hrs)
headless_en	bool	true	Run browser in headless mode
proxy_en	bool	true	Enable proxy rotation (requires valid proxy config)

Secrets (config/.secrets.json)

⚠️ This file contains sensitive credentials and is excluded from version control.

{
  "webshare_proxy_api_key": "your_api_key_here"
}

Setup:

cp config/.secrets.example.json config/.secrets.json
# Edit config/.secrets.json with your credentials
chmod 600 config/.secrets.json

Usage

# BURST mode: Schedule 10 simulated visits over 24 hours
./schedule 10 https://staging.yoursite.com

# STREAM mode: Maintain up to 10 concurrent simulated visitors
./schedule -s 10 https://staging.yoursite.com

Arguments

Argument	Description
<count>	Number of visits (BURST) or max concurrent visitors (STREAM)
<url>	Target URL (must include http:// or https://)
-s	Enable STREAM mode (optional)

Logging & Monitoring

• Logs are written to logs/schedule.log with rotation
• Runtime progress is displayed in stderr
• Visitor.click_count tracks simulated interactions for analytics validation

Safety Mechanisms

• RAM Safety: Scheduling halts if available RAM falls below 2× peak visitor usage
• Budget Enforcement: Total RAM usage never exceeds ram_budget_fraction × total_system_RAM
• Concurrency Limits: Hard caps prevent resource exhaustion
• Auto-Termination: Scheduler exits cleanly after scheduler_lifetime_secs

Contributing

Contributions are welcome for:

• More realistic user-behavior modeling
• Enhanced resource monitoring and reporting
• Integration with testing frameworks (pytest, locust, etc.)

Please open an issue to discuss significant changes before submitting a pull request.

License

MIT License — See LICENSE for details.