🚀 Advanced Speedtest CLI

A sophisticated, cross-platform command-line utility for measuring internet speed with precision. Engineered for accuracy, optimized for performance, and designed for modern networks.

---

📋 Table of Contents

• ✨ Features
• 🔧 System Requirements
• 📦 Installation
• ⚡ Quick Start
• 🎯 Usage Guide
• 🔬 Advanced Configuration
• 📊 Performance Metrics
• 🏗️ Architecture
• 🤝 Contributing
• 📞 Support

---

✨ Features

Core Capabilities

• 🎯 Precision Latency Testing - Real-time WebSocket-based ping measurement with millisecond accuracy
• 📥 Adaptive Download Testing - Multi-threaded parallel connections with intelligent stabilization detection
• 📤 Dynamic Upload Testing - Configurable concurrent uploads with real-time progress tracking
• 🌐 Server Diversity - Automatic server selection or manual picking from global speedtest infrastructure
• 👤 Dual-Mode Authentication - Seamless support for registered users and anonymous testing

User Experience

• 🎨 Color-Coded Results - Intuitive visual feedback with performance-based color indicators:
  • 🟢 Green (1-10ms / Excellent) - Premium connectivity
  • 🔵 Cyan (10-60ms / Good) - Solid performance
  • 🟡 Yellow (60-120ms / Acceptable) - Adequate connectivity
  • 🔴 Red (120+ms / Poor) - Degraded performance
• 📈 Real-Time Progress Visualization - tqdm-powered progress bars for all test phases
• ⚙️ Configurable Concurrency - Adjust parallel connection count (1-64) for optimal performance
• 🔒 Secure Authentication - Cookie-based session management with credential caching

Developer-Friendly

• ⚡ Quick Mode - Launch full speedtest with --q flag for automation and scripting
• 🔌 Modular Architecture - Clean separation of concerns with specialized test classes
• 📍 Comprehensive Logging - Detailed error handling and user feedback
• 🚀 Asynchronous Operations - Non-blocking ping monitoring concurrent with speed tests

---

🔧 System Requirements

Minimum Requirements

Component	Specification
Python	3.7 or higher
Memory	256 MB RAM
Network	Stable internet connection
OS	Windows, macOS, Linux

Recommended Setup

Component	Recommendation
Python	3.9+ for optimal performance
Memory	1 GB RAM or higher
Bandwidth	Minimum 1 Mbps for testing
OS	Latest stable version

---

📦 Installation

Option 1: Install from PyPI (Recommended)

The easiest way - install directly from PyPI:

Windows:

pip install adv-speedtest-cli
adv-speedtest-cli

macOS & Linux (Using pipx - Recommended):

# Install pipx if not already installed
sudo apt-get install pipx          # Ubuntu/Debian
brew install pipx                  # macOS

# Install the package
pipx install adv-speedtest-cli

# Configure PATH (important!)
pipx ensurepath

# Restart terminal or run:
source ~/.bashrc  # Linux
# Or manually add to PATH if needed

# Now use the command
adv-speedtest-cli

Linux/macOS (Alternative - Using pip):

pip install adv-speedtest-cli --break-system-packages

# If command not found, run as module:
python3 -m advanced_speedtest_cli

Option 2: Install from Source

Prerequisites: Ensure Python 3.7+ is installed:

python --version

Step 1: Clone Repository

git clone https://github.com/shakilofficial0/adv-speedtest-cli.git
cd adv-speedtest-cli

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Verify Installation

python speedtest.py --help
---

⚡ Quick Start

After Installation

Quick Mode - Execute immediate speedtest with default settings:

adv-speedtest-cli --q

Interactive Mode - Launch the full-featured menu:

adv-speedtest-cli

Alternative Commands

You can also use these equivalent commands:

advanced-speedtest
speedtest-cli

If Command Not Found

On Linux/macOS after pipx install:

# Option 1: Restart terminal (cleanest)
exit  # or close terminal window and reopen

# Option 2: Reload PATH manually
source ~/.bashrc     # Ubuntu/Debian
source ~/.zprofile   # macOS with zsh
source ~/.bash_profile  # macOS with bash

# Option 3: Run as Python module (always works)
python3 -m advanced_speedtest_cli --q

Using Source Installation

Quick Mode:

python speedtest.py --q

Interactive Mode:

python speedtest.py

Expected Output

✓ Ping Test Complete!
  Min: 8.62 ms (Very Good)
  Max: 9.42 ms (Very Good)
  Avg: 9.00 ms (Very Good)
  Median: 9.08 ms (Very Good)
  Samples: 10

✓ Download Complete!
  Speed: 276.20 Mbps
  Duration: 10.45s
  Downloaded: 250.00 MB

✓ Upload Complete!
  Speed: 255.96 Mbps
  Measurement Window: 3-12s (9s)
  Uploaded: 40.00 MB

SPEED TEST RESULTS
==================================================
✓ Test Complete!
  Ping: 9.00 ms (Very Good)
  Download: 276.20 Mbps
  Upload: 255.96 Mbps
==================================================

---

🎯 Usage Guide

Main Menu Navigation

1. Login - Authenticate with speedtest.net account (or skip for anonymous)
2. Select Server - Choose testing server or use auto-pick
3. Run SpeedTest - Execute comprehensive network analysis
4. Run SpeedTest and Share - Test and generate shareable result link
5. Settings - Configure test parameters
6. Logout - Clear authentication and session data

Settings Configuration

Speedtest Mode

• Single Connection - Conservative testing with 1 parallel connection
• Multiple Connections - Aggressive testing with configurable worker threads

Parallel Connections

• Range: 1 to 64 connections
• Default: 8 connections
• Impact: Higher connections = more aggressive network utilization

Server Selection

0. Auto Pick (Nearest Server)
1-N. Manual Server Selection
Search Server Option (ISP/Location/Name)

---

🔬 Advanced Configuration

Ping Test Protocol

Duration: 10 sequential packets
Timeout: 5 seconds per packet
Protocol: WebSocket (WSS)
Sampling: Real-time measurement

Download Test Strategy

Duration: 10-30 seconds (adaptive)
File Size: 250 MB
Skip Window: First 3 seconds (ramp-up)
Measurement: Overall bytes / total duration
Connections: Configurable (1-64)

Upload Test Strategy

Total Duration: 15 seconds fixed
Measurement Window: 3-12 seconds
Data Size: 40 MB per test
Skip Window: First 3 seconds
Measurement: Bytes in window / 9 seconds
Connections: Configurable (1-64)

---

📊 Performance Metrics

Speed Calculation Formula

Speed (Mbps) = (Total Bytes × 8) / (Duration × 1,000,000)

Accuracy Factors

• Stabilization: 3-second warm-up period to reach peak throughput
• Duration: Longer tests provide more stable results
• Concurrency: Multiple connections reduce per-connection overhead
• Network Conditions: Real-time network state directly impacts measurements

Quality Indicators

Metric	Threshold	Status
Ping	≤10ms	Exceptional
	10-60ms	Excellent
	60-120ms	Good
	>120ms	Needs Improvement
Download	>100 Mbps	Fiber/5G
	25-100 Mbps	Broadband
	<25 Mbps	Standard
Upload	>20 Mbps	Professional
	5-20 Mbps	Standard
	<5 Mbps	Limited

---

🏗️ Architecture

Class Structure

Config

Static configuration and API endpoints management

CookieManager

Persistent session and authentication token storage

LoginManager

User authentication workflow and credential validation

ServerManager

Server discovery, filtering, and auto-selection logic

State

Application state and user session tracking

Display

Terminal UI rendering and menu presentation

PingTest

WebSocket-based latency measurement with color coding

DownloadTest

Adaptive speed measurement with concurrent connection pooling

SpeedTest

Orchestration layer coordinating all test phases

Application

Main event loop and menu interaction handler

Data Flow

User Input
    ↓
Authentication (Optional)
    ↓
Server Selection
    ↓
Test Execution (Ping → Download → Upload)
    ↓
Results Aggregation
    ↓
Display & Share (Optional)

---

📝 Key Technologies

Technology	Purpose	Version
Python	Core language	3.7+
asyncio	Asynchronous operations	Built-in
websockets	Real-time ping protocol	Latest
requests	HTTP/HTTPS communication	Latest
tqdm	Progress visualization	Latest
colorama	Cross-platform colored output	Latest

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create feature branch: git checkout -b feature/enhancement
3. Implement changes with clear commits
4. Test thoroughly before submission
5. Submit Pull Request with detailed description

---

📞 Support

Getting Help

• 📧 Email: shakilofficial0@gmail.com
• 🐛 Issues: GitHub Issues
• 💡 Discussions: GitHub Discussions

Troubleshooting

Command Not Found (Ubuntu/Debian)

Issue: After installation, adv-speedtest-cli command is not found.

Solution 1: Using pipx (Recommended)

# If using pip/pip3, uninstall and reinstall with pipx
pip uninstall adv-speedtest-cli

# Install pipx (if not installed)
sudo apt-get install pipx

# Install with pipx
pipx install adv-speedtest-cli

# Configure PATH (IMPORTANT!)
pipx ensurepath

# Restart terminal or reload PATH:
source ~/.bashrc

# Now use the command
adv-speedtest-cli --q

Solution 2: Run as Python module (works immediately)

# If package is already installed, use as module
python3 -m advanced_speedtest_cli

# With quick mode
python3 -m advanced_speedtest_cli --q

# Create alias for convenience (add to ~/.bashrc)
echo 'alias adv-speedtest-cli="python3 -m advanced_speedtest_cli"' >> ~/.bashrc
source ~/.bashrc

Solution 3: Manual PATH configuration

# Add to ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc

Connection Failed

# Verify internet connectivity
ping google.com

# Check firewall/proxy settings
# Disable VPN if active

Import Errors

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Verify Python version
python --version

Timeout Issues

# Check network stability
# Reduce parallel connections in Settings
# Try with --q (quick mode)

---

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Speedtest.net - Infrastructure and testing methodology
• Python Community - Excellent standard library and ecosystem
• Open Source Contributors - All dependencies and inspirations

---

📊 Project Statistics

Language:       Python 3.7+
Lines of Code:  2,600+
Test Coverage:  Comprehensive
Platform:       Cross-Platform (Windows, macOS, Linux)
Active:         ✅ Under Active Development

---

🔐 Security & Privacy

• ✅ HTTPS Only - All connections encrypted
• ✅ Anonymous Support - Test without account
• ✅ Local Caching - Credentials stored locally only
• ✅ No Tracking - Privacy-focused design
• ✅ Open Source - Code transparency for security auditing

---

🎯 Roadmap

Upcoming Features

• JSON Export - Save results in structured format
• Historical Analysis - Track speed trends over time
• Save and Share Result - Auto Save and Share result in the speedtest

---

⭐ Show Your Support

If this project helped you, please consider:

• ⭐ Star this repository
• 🍴 Fork and contribute
• 🐛 Report issues and suggestions
• 📢 Share with your network

---

Created with ❤️ by Shakil Ahmed

#NetworkTesting #SpeedTest #Python #CLI #CrossPlatform #OpenSource #Networking #DevTools

---

Last Updated: January 2026 Version: 1.0.0