Grk26/speed-test-lib

:cloud: JSpeedTest : speed test client library for Java/Android

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.Grk26:speed-test-lib:1.33'
	}
	dependencies {
		implementation("com.github.Grk26:speed-test-lib:1.33")
	}
	<dependency>
	    <groupId>com.github.Grk26</groupId>
	    <artifactId>speed-test-lib</artifactId>
	    <version>1.33</version>
	</dependency>

                            
    libraryDependencies += "com.github.Grk26" % "speed-test-lib" % "1.33"
        
        

                            
    :dependencies [[com.github.Grk26/speed-test-lib "1.33"]]

Readme

JSpeedTest

Build Status Download Maven Central Coverage Status Codacy Badge Javadoc License

Speed Test client library for Java/Android with HTTP & FTP support

  • speed test download
  • speed test upload
  • download / upload progress monitoring
  • configurable hostname / port / uri (username & password for FTP)
  • configurable socket timeout and chunk size
  • configure upload file storage

Check a non-exhaustive list of compatible speed test server.

Include in your project

  • with Gradle, from jcenter or mavenCentral :
compile 'fr.bmartel:jspeedtest:1.30'

Usage

  • setup a speed test listener to monitor progress, completion and error catch :
SpeedTestSocket speedTestSocket = new SpeedTestSocket();

// add a listener to wait for speedtest completion and progress
speedTestSocket.addSpeedTestListener(new ISpeedTestListener() {

    @Override
    public void onCompletion(SpeedTestReport report) {
        // called when download/upload is complete
        System.out.println("[COMPLETED] rate in octet/s : " + report.getTransferRateOctet());
        System.out.println("[COMPLETED] rate in bit/s   : " + report.getTransferRateBit());
    }

    @Override
    public void onError(SpeedTestError speedTestError, String errorMessage) {
         // called when a download/upload error occur
    }

    @Override
    public void onProgress(float percent, SpeedTestReport report) {
        // called to notify download/upload progress
        System.out.println("[PROGRESS] progress : " + percent + "%");
        System.out.println("[PROGRESS] rate in octet/s : " + report.getTransferRateOctet());
        System.out.println("[PROGRESS] rate in bit/s   : " + report.getTransferRateBit());
    }

    @Override
    public void onInterruption() {
        // triggered when forceStopTask is called
    }
});

Download

  • HTTP download 1Mo from 2.testdebit.info
speedTestSocket.startDownload("http://2.testdebit.info/fichiers/1Mo.dat");
  • FTP download 1Mo from speedtest.tele2.net
speedTestSocket.startDownload("ftp://speedtest.tele2.net/1MB.zip");
  • FTP download 1Mo from ftp.otenet.gr with credentials (username/password), default is anonymous/no password
speedTestSocket.startDownload("ftp://speedtest:speedtest@ftp.otenet.gr/test1Mb.db");

Upload

  • HTTP upload 1Mo to 2.testdebit.info
speedTestSocket.startUpload("http://2.testdebit.info/", 1000000);
  • FTP upload a 1Mo file to speedtest.tele2.net
String fileName = SpeedTestUtils.generateFileName() + ".txt";
speedTestSocket.startUpload("ftp://speedtest.tele2.net/upload/" + fileName, 1000000);

Fixed duration download

Download during a fixed duration. Download will be stopped when the max duration is reached. At the end of the max duration, onInterruption is called if download has not be fully completed

  • HTTP download for 10s max, a 100 Mo file from 2.testdebit.info
speedTestSocket.startFixedDownload("http://2.testdebit.info/fichiers/100Mo.dat", 10000);
  • FTP download for 10s max, a 100 Mo file from speedtest.tele2.net
speedTestSocket.startFixedDownload("ftp://speedtest.tele2.net/100MB.zip");

Fixed duration Upload

Upload during a fixed duration. Upload will be stopped when the max duration is reached At the end of the max duration, onInterruption is called if upload has not be fully completed

  • HTTP upload for 10s max, a 10Mo file to 2.testdebit.info
speedTestSocket.startFixedUpload("http://2.testdebit.info/", 10000000, 10000);
  • FTP upload for 10s max, a 10Mo file to speedtest.tele2.net
String fileName = SpeedTestUtils.generateFileName() + ".txt";
speedTestSocket.startFixedUpload("ftp://speedtest.tele2.net/upload/" + fileName, 10000000, 10000);

Define report interval

You can define your own report interval (interval between each onDownloadProgress & onUploadProgress) in milliseconds.

  • HTTP download with download reports each 1.5 seconds
speedTestSocket.startDownload("http://2.testdebit.info/fichiers/1Mo.dat", 1500);
  • FTP download with download reports each 1.5 seconds
speedTestSocket.startDownload("ftp://speedtest.tele2.net/1MB.zip", 1500);
  • HTTP upload with upload reports each 1.5 seconds
speedTestSocket.startUpload("http://2.testdebit.info/", 10000000, 1500);
  • FTP upload with upload reports each 1.5 seconds
String fileName = SpeedTestUtils.generateFileName() + ".txt";
speedTestSocket.startUpload("ftp://speedtest.tele2.net/upload/" + fileName, 10000000, 1500);

Chain download/upload requests

You can chain multiple download/upload requests during a fixed duration. This way, there will be as much download/upload request until the end of the period

  • download repeat

The following will download regularly for 20 seconds a file of 1Mo with download report each 2 seconds. Download reports will appear in onReport callback of IRepeatListener instead of onDownloadProgress :

speedTestSocket.startDownloadRepeat("http://2.testdebit.info/fichiers/1Mo.dat",
    20000, 2000, new
            IRepeatListener() {
                @Override
                public void onCompletion(final SpeedTestReport report) {
                    // called when repeat task is finished
                }

                @Override
                public void onReport(final SpeedTestReport report) {
                    // called when a download report is dispatched
                }
            });
  • upload repeat

The following will upload regularly for 20 seconds a file of 1Mo with download report each 2 seconds. Upload reports will appear in onReport callback of IRepeatListener instead of onUploadProgress :

speedTestSocket.startUploadRepeat("http://2.testdebit.info/", 1000000
    20000, 2000, new
            IRepeatListener() {
                @Override
                public void onCompletion(final SpeedTestReport report) {
                    // called when repeat task is finished
                }

                @Override
                public void onReport(final SpeedTestReport report) {
                    // called when an upload report is dispatched
                }
            });

Get live download & upload

  • retrieve current download report :
SpeedTestReport getLiveDownloadReport()
  • retrieve current upload report :
SpeedTestReport getLiveUploadReport()

Set setup time

Setup time is the amount of time in milliseconds from which speed test will be calculated :

The following will set the setup time to 5 seconds which mean, the speed rate will begin to be computed 5 seconds after the speed test start :

  • download
speedTestSocket.setDownloadSetupTime(5000);
  • upload
speedTestSocket.setUploadSetupTime(5000);

Set upload file storage type

By default, data to be uploaded is stored in RAM, for large data it is recommended to used file storage :

speedTestSocket.setUploadStorageType(UploadStorageType.FILE_STORAGE);

It will create a temporary file containing random data. File will be deleted automatically at the end of the upload.

Set size of each packet sent to upload server

speedTestSocket.setUploadChunkSize(65535);

Set socket timeout value

You can set download/upload socket timeout in milliseconds :

speedTestSocket.setSocketTimeout(5000);

Set transfer rate precision

These settings are used to alter transfer rate float rounding / scale :

  • set RoundingMode :
speedTestSocket.setDefaultRoundingMode(RoundingMode.HALF_EVEN);

Default RoundingMode used for transfer rate calculation is HALF_EVEN. It can be override with :

  • set Scale :
speedTestSocket.setDefaultScale(4);

Default scale used for transfer rate calculation is 4

Android Integration

  • add Internet permission to manifest :
<uses-permission android:name="android.permission.INTERNET" />
  • use an AsyncTask to run your speed test :
public class SpeedTestTask extends AsyncTask<Void, Void, String> {

    @Override
    protected String doInBackground(Void... params) {

        SpeedTestSocket speedTestSocket = new SpeedTestSocket();

        // add a listener to wait for speedtest completion and progress
        speedTestSocket.addSpeedTestListener(new ISpeedTestListener() {

            @Override
            public void onCompletion(SpeedTestReport report) {
                // called when download/upload is finished
                Log.v("speedtest", "[COMPLETED] rate in octet/s : " + report.getTransferRateOctet());
                Log.v("speedtest", "[COMPLETED] rate in bit/s   : " + report.getTransferRateBit());
            }

            @Override
            public void onError(SpeedTestError speedTestError, String errorMessage) {
                // called when a download/upload error occur
            }

            @Override
            public void onProgress(float percent, SpeedTestReport report) {
                // called to notify download/upload progress
                Log.v("speedtest", "[PROGRESS] progress : " + percent + "%");
                Log.v("speedtest", "[PROGRESS] rate in octet/s : " + report.getTransferRateOctet());
                Log.v("speedtest", "[PROGRESS] rate in bit/s   : " + report.getTransferRateBit());
            }

            @Override
            public void onInterruption() {
                // triggered when forceStopTask is called
            }
        });

        speedTestSocket.startDownload("http://2.testdebit.info/fichiers/1Mo.dat");

        return null;
    }
}

Execute it with : new SpeedTestTask().execute();

Features examples

All following examples use speed test server 1.testdebit.info for HTTP and speedtest.tele2.net for FTP

  • HTTP download (1Mo)
./gradlew downloadFile
  • HTTP upload (1Mo)
./gradlew uploadFile
  • FTP download (1Mo)
./gradlew downloadFTP
  • FTP upload (1Mo)
./gradlew uploadFTP
  • download during a fixed duration (size: 100Mo, duration: 15s, report interval: 1s)
./gradlew fixedDownload
  • upload during a fixed duration (size: 100Mo, duration: 15s, report interval: 1s)
./gradlew fixedUpload
  • download repeatedly a file during a fixed duration (size:10Mo, duration 11s, report interval: 1s)
./gradlew repeatDownload
  • upload repeatedly a file during a fixed duration (size:1Mo, duration 11s, report interval: 1s)
./gradlew repeatUpload
  • successive 2 x (download + upload) repeatedly a file during a fixed duration (1 download size:1Mo, duration 3s, report interval: 1s following by 1 upload size:1Mo, duration 3s, report interval: 1s)
./gradlew repeatChain

Speed Test issues

It's important to choose an adequate speed test server depending on latency/jitter. This library is not responsible for the speed test server choice.

Note that this library :

  • doesn't adjust the chunk size depending on the connection speed either
  • doesn't provide pre-estimation of the connection speed based on small chunk sent to/from server
  • doesn't detect anomaly either (for instance taking away X% slowest chunk and X% fastest chunk downloaded)

This library does provide an average of transfer rate for all individual chunks read/written for download/upload.

The 2 following links describe the process of speedtest.net :

  • http://www.ookla.com/support/a21110547/what-is-the-test-flow-and-methodology-for-the-speedtest
  • https://support.speedtest.net/hc/en-us/articles/203845400-How-does-the-test-itself-work-How-is-the-result-calculated-

Compatibility

JRE 1.7 compliant

Build & test

  • build without test :
./gradlew clean build -x test
  • build with test :
./gradlew clean build
  • run specific test
./gradlew test --tests "fr.bmartel.speedtest.test.SpeedTestFunctionalTest"

External libraries

License

The MIT License (MIT) Copyright (c) 2016 Bertrand Martel