✨ Add adaptive size and timeout capability to gain time

README.md

@@ -40,6 +40,16 @@ uv tool install speedtest-cloudflare-cli
 pip install speedtest-cloudflare-cli
 ```
 
+## Features
+
+- ⏱️ **Time-Based Testing** - 10 second default timeout per test for consistent, fast results
+- 🚀 **Adaptive Test Sizing** - Automatically adjusts test size based on your connection speed
+- 📊 **Comprehensive Metrics** - Download/upload speed, ping, jitter, and HTTP latency
+- 🌍 **Cloudflare Infrastructure** - Tests using Cloudflare's global network
+- 🎨 **Beautiful Output** - Rich terminal interface with progress bars and tables
+- 📄 **Multiple Output Formats** - Console, JSON, and interactive web dashboard
+- 🔒 **Privacy Focused** - No tracking, no accounts, open source
+
 ## Usage
 
 Run the following command to test your internet speed.
@@ -50,6 +60,16 @@ speedtest-cli
 
 ![Speedtest output](docs/assets/speedtest_output.png)
 
+By default, each test (download/upload) runs for **10 seconds** and calculates speed based on data transferred. You can customize the timeout:
+
+```bash
+# 5 second timeout per test
+speedtest-cli --timeout 5
+
+# 20 second timeout for more accuracy
+speedtest-cli --timeout 20
+```
+
 For more information, run the --help command.
 ```bash
 speedtest-cli --help

docs/faq.md

@@ -262,6 +262,87 @@ This is **normal** and expected because:
 3. Use same connection type (Wi-Fi vs Ethernet)
 4. Close background applications
 
+### Why Does My Test Size Change Each Time?
+
+**Problem:** Test size varies between runs
+
+**Explanation:**
+
+This is **adaptive mode** (enabled by default). It automatically adjusts test size based on your connection speed
+
+**How It Works:**
+
+1. Runs a quick 5MB probe test
+2. Estimates your connection speed
+3. Calculates optimal test size for ~7.5 second duration
+4. Uses size between 1MB and 200MB
+
+**To Disable:**
+
+```bash
+# Use fixed 30MB size
+speedtest-cli --no-adaptive
+
+# Or specify manual size
+speedtest-cli --download_size 50
+```
+
+### How Do I Disable Adaptive Mode?
+
+**Problem:** Want to use fixed test sizes
+
+**Solutions:**
+
+1. **Disable adaptive mode:**
+
+   ```bash
+   speedtest-cli --no-adaptive
+   ```
+
+2. **Specify manual sizes** (automatically disables adaptive):
+
+   ```bash
+   speedtest-cli --download_size 50 --upload_size 25
+   ```
+
+3. **For scripts** expecting fixed sizes:
+
+   ```bash
+   speedtest-cli --no-adaptive --json-output results.json
+   ```
+
+**Use Cases for Disabling:**
+
+- Comparing results with specific test sizes
+- Meeting exact test requirements
+- Legacy scripts expecting fixed data volumes
+- Benchmarking with consistent parameters
+
+### What If the Probe Test Gives Wrong Results?
+
+**Problem:** Probe test estimates incorrect speed
+
+**Explanation:**
+
+The probe test is intentionally short (1-2 seconds) and may not always be perfectly accurate. This is okay because:
+
+- It's designed for a quick estimate, not precision
+- Falls back to default 30MB if probe fails
+- Main test still provides accurate final results
+- Uses min/max boundaries (1MB - 200MB) to prevent extremes
+
+**If Consistently Inaccurate:**
+
+```bash
+# Disable adaptive mode
+speedtest-cli --no-adaptive
+
+# Or specify exact sizes
+speedtest-cli -ds 100 -us 50
+```
+
+**Note:** The probe's purpose is to optimize test duration, not to measure your exact speed. The main test provides the accurate measurement.
+
 ### Web Dashboard Won't Open
 
 **Problem:** `--web_view` doesn't open browser

docs/features.md

@@ -466,6 +466,65 @@ speedtest-cli -ds 100 -us 50
 | 100-500 Mbps    | 100-200 MB              | 50-100 MB              |
 | > 500 Mbps      | 200+ MB                 | 100+ MB                |
 
+### Adaptive Test Sizing
+
+**NEW:** Automatically adjusts test sizes based on your connection speed.
+
+**How It Works:**
+
+1. Runs a quick 5MB probe test (takes 1-2 seconds)
+2. Estimates your connection speed from probe results
+3. Calculates optimal test size for ~7.5 second test duration
+4. Applies min/max boundaries (1MB - 200MB)
+5. Runs main test with adaptive size
+
+**Benefits:**
+
+- **Fast for slow connections**: 1 Mbps connection uses 1MB test (not 30MB!)
+- **Accurate for fast connections**: 500 Mbps connection uses 200MB test
+- **Saves time**: No more waiting for large downloads on slow connections
+- **Balanced accuracy**: Tests run long enough for accurate measurements
+
+**Enabled by Default:**
+
+```bash
+# Adaptive mode is enabled automatically
+speedtest-cli
+
+# Example output:
+# Running probe test to detect connection speed...
+# ✓ Detected speed: ~56.1 Mbps
+# Adaptive mode: Using 53MB for download test
+```
+
+**Disable Adaptive Mode:**
+
+```bash
+# Use fixed 30MB size (legacy behavior)
+speedtest-cli --no-adaptive
+
+# Manual sizes always disable adaptive
+speedtest-cli --download_size 50  # Uses exactly 50MB
+```
+
+**Example Scenarios:**
+
+| Connection Speed | Probe Detects | Adaptive Size | Test Duration |
+|-----------------|---------------|---------------|---------------|
+| 1 Mbps          | ~1 Mbps       | 1 MB          | ~8 seconds    |
+| 10 Mbps         | ~10 Mbps      | 9 MB          | ~7 seconds    |
+| 50 Mbps         | ~50 Mbps      | 47 MB         | ~7.5 seconds  |
+| 100 Mbps        | ~100 Mbps     | 94 MB         | ~7.5 seconds  |
+| 500 Mbps        | ~480 Mbps     | 200 MB (max)  | ~3.2 seconds  |
+| 1000 Mbps       | ~950 Mbps     | 200 MB (max)  | ~1.6 seconds  |
+
+**When to Disable:**
+
+- Comparing results with specific test sizes
+- Meeting exact test requirements for diagnostics
+- Using scripts that expect specific data volumes
+- Benchmarking with consistent parameters
+
 ---
 
 ## IPv6 Support

docs/usage.md

@@ -157,6 +157,50 @@ speedtest-cli -a 3
 speedtest-cli -a 5
 ```
 
+#### `--adaptive` / `--no-adaptive`
+
+Enable or disable adaptive test sizing based on connection speed.
+
+```bash
+# Adaptive mode is enabled by default
+speedtest-cli
+
+# Explicitly disable adaptive mode
+speedtest-cli --no-adaptive
+```
+
+**Default:** Enabled  
+**Use Case:** 
+- **Enabled (default)**: Automatically adjusts test size for optimal duration
+- **Disabled**: Uses fixed 30MB test size (legacy behavior)
+
+**How It Works:**
+1. Runs a quick 5MB probe test to estimate your speed
+2. Calculates optimal test size for ~7.5 second duration
+3. Uses adaptive size (between 1MB and 200MB)
+
+**Example:**
+```bash
+# Let adaptive mode optimize test size (default)
+speedtest-cli
+
+# Output:
+# Running probe test to detect connection speed...
+# ✓ Detected speed: ~56.1 Mbps
+# Adaptive mode: Using 53MB for download test
+
+# Disable adaptive mode to use fixed 30MB
+speedtest-cli --no-adaptive
+
+# Note: Manual size specification automatically disables adaptive
+speedtest-cli --download_size 50  # Uses exactly 50MB, adaptive disabled
+```
+
+**Benefits:**
+- **Faster tests** on slow connections (no more waiting for 30MB on 1 Mbps!)
+- **More accurate** on fast connections (uses larger test sizes)
+- **Consistent duration** (~7-10 seconds regardless of connection speed)
+
 ---
 
 ### Output Options