diff --git a/README.md b/README.md index 4190e94..26c68e7 100644 --- a/README.md +++ b/README.md @@ -13,78 +13,262 @@ A modern, high-performance web analytics tool that allows users to run Google Li ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15+-4169E1?style=flat-square&logo=postgresql&logoColor=white) ![Lighthouse](https://img.shields.io/badge/Lighthouse-13.0+-F44B21?style=flat-square&logo=lighthouse&logoColor=white) -[Features](#-essential-features) • [Visual Tour](#-visual-tour) • [Getting Started](#-getting-started) • [Deployment](#-deployment) +[Features](#-comprehensive-features) • [Visual Tour](#-visual-tour) • [Getting Started](#-getting-started) • [Deployment](#-deployment) --- -## ✨ Essential Features +## ✨ Comprehensive Features -* **⚡ Core Web Vitals Analysis**: Comprehensive breakdown of LCP, CLS, and TBT metrics. -* **📱 Multi-Device Emulation**: Toggle between Desktop (1920x1080) and Mobile (Moto G4) emulation modes. -* **🔒 User Isolation & Privacy**: - * Test history is strictly isolated per user via client-side UUIDs. - * No shared history between different users. -* **🚀 Concurrency Queue System**: - * Intelligent backend queue prevents server overload. - * Supports simultaneous users without crashing (FIFO processing). -* **💾 Persistent History**: Automatically saves your recent test runs using a PostgreSQL database. -* **📊 Detailed Reports**: Generates full HTML Lighthouse reports and JSON summaries. -* **📸 Visual Filmstrip**: Captures frame-by-frame screenshots of the page load experience. +### 🎯 **Multi-Run Statistics** +Run tests multiple times (1, 3, 5, or 10 runs) to get statistically significant results. The system automatically calculates: +- **Median Performance Score** ⭐ (identifies the most representative run) +- **Average & Standard Deviation** for all Core Web Vitals +- **Individual Run Comparison** with detailed metrics for each test + +*Perfect for eliminating variance and getting reliable performance data.* + +
+ Multi-Run Selector +
+ +--- + +### 📊 **Performance Grades (A-F)** +Industry-standard grading system for 6 critical metrics: +- **First Contentful Paint (FCP)** - When users first see content +- **Largest Contentful Paint (LCP)** - Main content rendering time +- **Cumulative Layout Shift (CLS)** - Visual stability score +- **Total Blocking Time (TBT)** - Interactivity delays +- **Speed Index** - How quickly content is visually displayed +- **Time to Interactive (TTI)** - When page becomes fully interactive + +Each metric is color-coded (Green A → Red F) based on WebPageTest standards. + +
+ Performance Grades +
+ +--- + +### 📈 **Request Waterfall Chart** +Detailed visual timeline showing: +- **Sequential request loading** with precise timing +- **HTTP status codes** (200 = success, 404 = not found, etc.) +- **Resource types** (HTML, CSS, JS, Images, Fonts) +- **File sizes** and transfer times +- **Request/Response headers** for debugging +- **Vertical time grid** for easy time tracking + +
+ Waterfall Chart +
+ +--- + +### 🔗 **Connection View** +Advanced networking analysis that groups requests by their socket connection: +- **Connection Reuse Detection** (♻️ Reused vs 🆕 New) +- **HTTP/2 Multiplexing Visualization** - See parallel requests +- **Domain Grouping** - Identify third-party dependencies +- **Protocol Display** (HTTP/1.1, HTTP/2, HTTP/3) + +*Helps optimize connection pooling and identify opportunities for HTTP/2 upgrades.* + +
+ Connection View +
+ +--- + +### 📦 **Content Breakdown Analysis** +Interactive pie chart and detailed table showing: +- **Resource Type Distribution** (Document, Stylesheet, Script, Image, Font, Other) +- **Request Count** per type +- **Total Size & Transfer Size** (before/after compression) +- **Optimization Opportunities** - Identifies large unoptimized images + +
+ Content Breakdown +
+ +--- + +### 🖼️ **Image Gallery & Optimization** +Dedicated image analysis tool that displays: +- **All loaded images** with thumbnails +- **Format detection** (WebP, AVIF, PNG, JPEG, SVG, GIF) +- **Size warnings** for images over 100KB +- **Optimization suggestions** (e.g., "Switch to WebP for 30% savings") +- **Total statistics** (count, total size, average size) + +--- + +### 🔄 **Test Comparison** +Select up to 10 previous tests and compare them side-by-side: +- **Performance score trends** +- **Core Web Vitals differences** +- **Page load time variations** +- **Resource count changes** + +*Perfect for tracking performance improvements over time or A/B testing different configurations.* + +--- + +### 🕰️ **Recent Tests with Clickable URLs** +Your test history, enhanced: +- **Click any website URL** to instantly reload previous results +- **Checkboxes for comparison** selection +- **Device indicators** (📱 Mobile / 💻 Desktop) +- **Performance scores** at a glance +- **Quick access buttons** (Waterfall, View Report) + +
+ Recent Tests +
+ +--- + +### 🔐 **Privacy & User Isolation** +- **Client-side UUID tracking** - Your tests stay yours +- **No shared history** between users +- **Automatic cleanup** - Old tests are periodically archived + +--- + +### ⚙️ **Additional Features** +- **📱 Device Emulation** - Toggle between Desktop (1920x1080) and Mobile (Moto G4) +- **💾 Persistent Storage** - PostgreSQL database for reliable history +- **📄 Export Capabilities** - Download HAR files and JSON reports +- **🚀 Request Queue System** - Handles concurrent users without crashes +- **⏱️ Real-time Progress** - Live updates during multi-run tests +- **🎨 Dark Mode Interface** - Easy on the eyes, professional design + +--- ## 📸 Visual Tour
-

Desktop Analysis Results

- Desktop Results +

🖥️ Desktop Dashboard View

+ Desktop Dashboard +

Full-featured dashboard showing test configuration, results, and analysis tools



-

Mobile Responsive Dashboard

- Mobile Dashboard View +

📱 Mobile Responsive Design

+ Mobile Dashboard +

Fully optimized mobile experience - test on any device

+--- + ## 🚀 Getting Started ### Prerequisites -* Node.js v20+ -* Chromium / Google Chrome installed -* PostgreSQL +- **Node.js** v20 or higher +- **Google Chrome** or Chromium +- **PostgreSQL** 15+ (for test history) ### Installation -1. Clone the repository: - ```bash - git clone https://github.com/DeNNiiInc/Web-Page-Performance-Test.git - cd Web-Page-Performance-Test - ``` +1. **Clone the repository:** + ```bash + git clone https://github.com/DeNNiiInc/Web-Page-Performance-Test.git + cd Web-Page-Performance-Test + ``` -2. Install dependencies: - ```bash - npm install - ``` +2. **Install dependencies:** + ```bash + npm install + ``` -3. Apply Permissions (Optional): - ```bash - chmod +x config-fix.sh - ``` +3. **Configure the database:** + - Update `lib/db-config.js` with your PostgreSQL credentials + - Run migrations: + ```bash + cd migrations + chmod +x run-migration.sh + ./run-migration.sh + ``` -4. Start the server: - ```bash - npm start - ``` - The application will run on `http://localhost:3000`. +4. **Start the server:** + ```bash + npm start + ``` + The application will run on `http://localhost:3000` + +### Usage + +1. **Enter a website URL** (e.g., `https://example.com`) +2. **Select device type** (Desktop or Mobile) +3. **Choose number of runs** (1 for quick test, 3-5 for reliable median) +4. **Click "Run Test"** and wait for results +5. **Explore the data:** + - View performance grades and Core Web Vitals + - Click "View Waterfall Chart" for detailed request timeline + - Check "View Image Gallery" for optimization opportunities + - Select tests to compare performance over time + +--- ## 🛠️ Deployment -This project includes automated deployment scripts for Proxmox/Linux environments. +This project includes automated deployment for production environments. -* **Automated Sync**: `auto-sync-robust.sh` handles pulling changes and restarting services only when necessary. -* **Crednetial Safety**: `deploy-config.json` and `.env` files are strictly git-ignored. -* **License**: Distributed under the **GPL-3.0** License. +### Automated Deployment (Linux/Proxmox) +- **Auto-sync script** (`auto-sync-robust.sh`) pulls GitHub changes every 60 seconds +- **Systemd service** manages the Node.js application +- **Environment variables** stored in `.env` (git-ignored for security) +- **Graceful restarts** only when code changes are detected + +### Manual Deployment +1. Pull latest code: `git pull origin main` +2. Install dependencies: `npm install` +3. Run migrations: `cd migrations && ./run-migration.sh` +4. Restart service: `systemctl restart web-page-performance-test` + +### Configuration Files +- `lib/db-config.js` - Database connection settings +- `deploy-config.json` - Deployment credentials (git-ignored) +- `.env` - Environment variables (git-ignored) --- + +## 🔧 Technology Stack + +| Component | Technology | +|-----------|-----------| +| **Backend** | Node.js 20+ with Express 4.18+ | +| **Testing Engine** | Google Lighthouse 13.0+ | +| **Browser** | Chrome Launcher (headless) | +| **Database** | PostgreSQL 15+ | +| **Frontend** | Vanilla JavaScript, CSS3, HTML5 | +| **Charts** | Canvas-based custom rendering | +| **Analysis** | HAR file parsing, statistical calculations | + +--- + +## 📝 License + +Distributed under the **GPL-3.0** License. See `LICENSE` file for more information. + +--- + +## 🤝 Contributing + +Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/DeNNiiInc/Web-Page-Performance-Test/issues). + +--- + +## 📧 Support + +For questions or support, please open an issue on GitHub or contact **Beyond Cloud Technology**. + +--- +
- Developed and maintained by Beyond Cloud Technology. + Developed and maintained by Beyond Cloud Technology +
+ ⭐ Star this repo if you find it useful!
diff --git a/docs/images/connection_view.png b/docs/images/connection_view.png new file mode 100644 index 0000000..859a4c7 Binary files /dev/null and b/docs/images/connection_view.png differ diff --git a/docs/images/content_breakdown.png b/docs/images/content_breakdown.png new file mode 100644 index 0000000..0169c44 Binary files /dev/null and b/docs/images/content_breakdown.png differ diff --git a/docs/images/dashboard_desktop.png b/docs/images/dashboard_desktop.png new file mode 100644 index 0000000..cc487dd Binary files /dev/null and b/docs/images/dashboard_desktop.png differ diff --git a/docs/images/mobile_dashboard.png b/docs/images/mobile_dashboard.png index 5388442..ac8149e 100644 Binary files a/docs/images/mobile_dashboard.png and b/docs/images/mobile_dashboard.png differ diff --git a/docs/images/multirun_selector.png b/docs/images/multirun_selector.png new file mode 100644 index 0000000..b480221 Binary files /dev/null and b/docs/images/multirun_selector.png differ diff --git a/docs/images/performance_grades.png b/docs/images/performance_grades.png new file mode 100644 index 0000000..66eb1ef Binary files /dev/null and b/docs/images/performance_grades.png differ diff --git a/docs/images/recent_tests.png b/docs/images/recent_tests.png new file mode 100644 index 0000000..fcacc4d Binary files /dev/null and b/docs/images/recent_tests.png differ diff --git a/docs/images/waterfall_chart.png b/docs/images/waterfall_chart.png new file mode 100644 index 0000000..0db5b5c Binary files /dev/null and b/docs/images/waterfall_chart.png differ