Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jrquick17/ng-speed-test

A light weight Angular 2+ library for checking internet speed
https://github.com/jrquick17/ng-speed-test

Last synced: 4 months ago
JSON representation

A light weight Angular 2+ library for checking internet speed

Awesome Lists containing this project

README 

          
# ng-speed-test



[![npm version](https://img.shields.io/npm/v/ng-speed-test.svg)](https://www.npmjs.com/package/ng-speed-test)

[![npm license](https://img.shields.io/npm/l/ng-speed-test.svg)](https://www.npmjs.com/package/ng-speed-test/)

[![npm downloads](https://img.shields.io/npm/dt/ng-speed-test.svg)](https://www.npmjs.com/package/ng-speed-test)

[![npm monthly downloads](https://img.shields.io/npm/dm/ng-speed-test.svg)](https://www.npmjs.com/package/ng-speed-test)

[![Angular](https://img.shields.io/badge/Angular-16%2B-red.svg)](https://angular.io/)



A modern, lightweight Angular library for testing internet connection speed with built-in network monitoring.



🚀 **[Try the Live Demo](https://ng-speed-test.jrquick.com)**



![Speed Test Demo](example.gif)



## ✨ Features



- 🎯 **Accurate Speed Testing** - Uses multiple iterations for reliable results

- 🔄 **Network Status Monitoring** - Real-time online/offline detection

- ⚡ **Modern Fetch API** - Better performance and error handling

- 🎨 **TypeScript Support** - Full type definitions included

- 📱 **Mobile Friendly** - Works on all devices and browsers

- 🔧 **Highly Configurable** - Customize file sizes, iterations, and retry logic

- 🆕 **Angular 16-20 Compatible** - Works with latest Angular versions



## 📋 Table of Contents



- [Installation](#-installation)

- [Quick Start](#-quick-start)

- [Configuration](#-configuration)

- [API Reference](#-api-reference)

- [Examples](#-examples)

- [Browser Support](#-browser-support)

- [Contributing](#-contributing)



## 🚀 Installation



```bash

npm install ng-speed-test --save

```



## ⚡ Quick Start



### 1. Import the Module



Add `SpeedTestModule` to your app module:



```typescript

import { SpeedTestModule } from 'ng-speed-test';



@NgModule({

  imports: [

    SpeedTestModule

  ],

})

export class AppModule { }

```



### 2. Inject the Service



```typescript

import { Component } from '@angular/core';

import { SpeedTestService } from 'ng-speed-test';



@Component({

  selector: 'app-speed-test',

  template: `

    


      

        {{ isLoading ? 'Testing...' : 'Test Speed' }}

      

      


        Your speed: {{ speedResult.mbps | number:'1.2-2' }} Mbps

      


    


  `

})

export class SpeedTestComponent {

  isLoading = false;

  speedResult: any;



  constructor(private speedTestService: SpeedTestService) {}



  runSpeedTest() {

    this.isLoading = true;

    

    this.speedTestService.getSpeedTestResult().subscribe({

      next: (result) => {

        this.speedResult = result;

        this.isLoading = false;

      },

      error: (error) => {

        console.error('Speed test failed:', error);

        this.isLoading = false;

      }

    });

  }

}

```



## 🛠️ Configuration



### Basic Configuration



```typescript

const customSettings = {

  iterations: 5,           // Run 5 tests for better accuracy

  retryDelay: 1000,       // Wait 1 second between retries

  file: {

    path: 'https://example.com/test-file.jpg',

    size: 1048576,        // 1MB in bytes

    shouldBustCache: true // Prevent browser caching

  }

};



this.speedTestService.getMbps(customSettings).subscribe(speed => {

  console.log(`Speed: ${speed} Mbps`);

});

```



### Available Test Files



Pre-configured test files hosted on GitHub:



| Size | Actual Size (bytes) | URL |

|------|-------------------|-----|

| 500KB | 408,949 | `https://raw.githubusercontent.com/jrquick17/ng-speed-test/.../500kb.jpg` |

| 1MB | 1,197,292 | `https://raw.githubusercontent.com/jrquick17/ng-speed-test/.../1mb.jpg` |

| **5MB** | 4,952,221 | `https://raw.githubusercontent.com/jrquick17/ng-speed-test/.../5mb.jpg` *(default)* |

| 13MB | 13,848,150 | `https://raw.githubusercontent.com/jrquick17/ng-speed-test/.../13mb.jpg` |



## 📚 API Reference



### Core Methods



#### `getSpeedTestResult(settings?)`

Returns comprehensive speed test results with duration info.



```typescript

this.speedTestService.getSpeedTestResult().subscribe(result => {

  console.log('Speed:', result.mbps, 'Mbps');

  console.log('Duration:', result.duration, 'seconds');

  console.log('Bits per second:', result.bps);

  console.log('Kilobits per second:', result.kbps);

});

```



#### `getMbps(settings?)`

Get speed in megabits per second.



```typescript

this.speedTestService.getMbps().subscribe(speed => {

  console.log('Speed:', speed, 'Mbps');

});

```



#### `getKbps(settings?)`

Get speed in kilobits per second.



```typescript

this.speedTestService.getKbps().subscribe(speed => {

  console.log('Speed:', speed, 'Kbps');

});

```



#### `getBps(settings?)`

Get speed in bits per second.



```typescript

this.speedTestService.getBps().subscribe(speed => {

  console.log('Speed:', speed, 'bps');

});

```



### Network Monitoring



#### `isOnline()`

Check network connectivity.



```typescript

this.speedTestService.isOnline().subscribe(isOnline => {

  if (!isOnline) {

    console.log('No internet connection');

  }

});

```



#### `getNetworkStatus()`

Get detailed network information (when available).



```typescript

this.speedTestService.getNetworkStatus().subscribe(status => {

  console.log('Online:', status.isOnline);

  console.log('Connection type:', status.effectiveType); // '4g', 'wifi', etc.

  console.log('Downlink speed:', status.downlink); // Estimated speed

});

```



### Configuration Options



| Option | Type | Default | Description |

|--------|------|---------|-------------|

| `iterations` | number | 3 | Number of tests to run for averaging |

| `retryDelay` | number | 500 | Milliseconds to wait between retries |

| `file.path` | string | GitHub 5MB image | URL of test file |

| `file.size` | number | 4,952,221 | File size in bytes |

| `file.shouldBustCache` | boolean | true | Add cache-busting parameter |



## 💡 Examples



### Advanced Speed Test with Progress



```typescript

import { Component } from '@angular/core';

import { SpeedTestService } from 'ng-speed-test';



@Component({

  template: `

    


      
Internet Speed Test


      

      

      


        Status: {{ isOnline ? 'Online' : 'Offline' }}

      


      

      

      


        

          500 KB Test

          1 MB Test

          5 MB Test

          13 MB Test

        

        

        

        

        

          {{ isRunning ? 'Testing...' : 'Start Test' }}

        

      


      

      

      


        


          


        


        
{{ progressText }}


      


      

      

      


        
Results


        


          


            {{ lastResult.mbps | number:'1.2-2' }}

            Mbps

          


          


            {{ lastResult.kbps | number:'1.0-0' }}

            Kbps

          


          


            {{ lastResult.duration | number:'1.2-2' }}

            seconds

          


        


      


    


  `,

  styles: [`

    .speed-test { max-width: 600px; margin: 0 auto; padding: 20px; }

    .status { padding: 10px; border-radius: 5px; margin-bottom: 20px; }

    .status.online { background: #d4edda; color: #155724; }

    .controls { display: flex; gap: 10px; margin-bottom: 20px; }

    .progress-bar { width: 100%; height: 8px; background: #e0e0e0; border-radius: 4px; }

    .fill { height: 100%; background: #007bff; transition: width 0.3s; }

    .result-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 15px; }

    .result-item { text-align: center; padding: 15px; background: #f8f9fa; border-radius: 5px; }

  `]

})

export class AdvancedSpeedTestComponent {

  isOnline = true;

  isRunning = false;

  progress = 0;

  progressText = '';

  lastResult: any = null;

  selectedSize = '5mb';

  iterations = 3;



  private fileSizes = {

    '500kb': { size: 408949, path: 'https://raw.githubusercontent.com/.../500kb.jpg' },

    '1mb': { size: 1197292, path: 'https://raw.githubusercontent.com/.../1mb.jpg' },

    '5mb': { size: 4952221, path: 'https://raw.githubusercontent.com/.../5mb.jpg' },

    '13mb': { size: 13848150, path: 'https://raw.githubusercontent.com/.../13mb.jpg' }

  };



  constructor(private speedTestService: SpeedTestService) {

    // Monitor network status

    this.speedTestService.isOnline().subscribe(status => {

      this.isOnline = status;

    });

  }



  runTest() {

    if (!this.isOnline) return;



    this.isRunning = true;

    this.progress = 0;

    this.progressText = 'Initializing...';



    const fileConfig = this.fileSizes[this.selectedSize];

    const settings = {

      iterations: this.iterations,

      file: {

        path: fileConfig.path,

        size: fileConfig.size,

        shouldBustCache: true

      }

    };



    // Simulate progress

    const progressInterval = setInterval(() => {

      if (this.progress < 90) {

        this.progress += Math.random() * 10;

        this.progressText = `Testing... ${Math.floor(this.progress)}%`;

      }

    }, 200);



    this.speedTestService.getSpeedTestResult(settings).subscribe({

      next: (result) => {

        clearInterval(progressInterval);

        this.progress = 100;

        this.progressText = 'Complete!';

        this.lastResult = result;

        this.isRunning = false;

      },

      error: (error) => {

        clearInterval(progressInterval);

        console.error('Test failed:', error);

        this.isRunning = false;

      }

    });

  }

}

```



### Simple Network Monitor



```typescript

@Component({

  template: `

    


      {{ networkStatus.isOnline ? 'Connected' : 'Disconnected' }}

      

        ({{ networkStatus.effectiveType }})

      

    


  `

})

export class NetworkMonitorComponent {

  networkStatus = { isOnline: true, effectiveType: null };



  constructor(private speedTestService: SpeedTestService) {

    this.speedTestService.getNetworkStatus().subscribe(status => {

      this.networkStatus = status;

    });

  }

}

```



## 🌐 Browser Support



- **Chrome** 60+

- **Firefox** 55+

- **Safari** 12+

- **Edge** 79+

- **Mobile browsers** with Fetch API support



## 🔧 Angular Compatibility



| ng-speed-test | Angular |

|---------------|---------|

| 3.x | 16, 17, 18, 19, 20 |

| 2.x | 12, 13, 14, 15 |

| 1.x | 8, 9, 10, 11 |



## 🐛 Troubleshooting



### Common Issues



**CORS Errors**

- Use the provided test files or ensure your custom files have proper CORS headers

- GitHub-hosted test files are CORS-enabled



**Inaccurate Results**

- Increase `iterations` for better accuracy (recommended: 5-10)

- Use appropriate file sizes (1-5MB for most connections)

- Ensure stable network during testing



**TypeScript Errors**

- Make sure you're importing from `'ng-speed-test'`

- Check that your Angular version is compatible



## 🤝 Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



### Development Setup



```bash

# Clone the repository

git clone https://github.com/jrquick17/ng-speed-test.git



# Install dependencies

npm install



# Run the demo

npm run demo



# Build the library

npm run build



# Run tests

npm run test

```



## 📄 License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



## 🙏 Acknowledgments



- Created by [Jeremy Quick](https://jrquick.com)

- Inspired by the need for reliable network testing in Angular applications

- Thanks to all [contributors](https://github.com/jrquick17/ng-speed-test/graphs/contributors)



## 🔗 Links



- [Live Demo](https://ng-speed-test.jrquick.com)

- [GitHub Repository](https://github.com/jrquick17/ng-speed-test)

- [NPM Package](https://www.npmjs.com/package/ng-speed-test)

- [Issues & Support](https://github.com/jrquick17/ng-speed-test/issues)

- [Jeremy's Website](https://jrquick.com)



---



**Made with ❤️ for the Angular community**