speedtest.js

mirror of https://github.com/librespeed/speedtest.git synced 2026-05-13 16:26:38 +00:00

Table of Contents

List of functions in the Speedtest class

getState()
setParameter(parameter,value)
addTestPoint(server)
addTestPoints(list)
loadServerList(url,result)
getSelectedServer()
setSelectedServer()
selectServer(result)
start()
abort()

This is the main interface between your webpage and the speedtest. It hides the speedtest web worker to the page, and provides many convenient functions to control the test.

You can think of this as a finite state machine. These are the states (use getState() to see them):

0: here you can change the speedtest settings (such as test duration) with the setParameter("parameter",value) function. From here you can either start the test using start() (goes to state 3) or you can add multiple test points using addTestPoint(server) or addTestPoints(serverList) (goes to state 1). Additionally, this is the perfect moment to set up callbacks for the onupdate(data) and onend(aborted) events.

1: here you can add test points. You only need to do this if you want to use multiple test points. A server is defined as an object like this:

{
    name: "User friendly name",
    server:"http://yourBackend.com/",     <---- URL to your server. You can specify http:// or https://. If your server supports both, just write // without the protocol
    dlURL:"garbage.php"    <----- path to garbage.php or its replacement on the server
    ulURL:"empty.php"    <----- path to empty.php or its replacement on the server
    pingURL:"empty.php"    <----- path to empty.php or its replacement on the server. This is used to ping the server by this selector
    getIpURL:"getIP.php"    <----- path to getIP.php or its replacement on the server
}

While in state 1, you can only add test points, you cannot change the test settings. When you're done, use selectServer(callback) to select the test point with the lowest ping. This is asynchronous, when it's done, it will call your callback function and move to state 2. Calling setSelectedServer(server) will manually select a server and move to state 2.

2: test point selected, ready to start the test. Use start() to begin, this will move to state 3
3: test running. Here, your onupdate event calback will be called periodically, with data coming from the worker about speed and progress. A data object will be passed to your onupdate function, with the following items: - dlStatus: download speed in mbps - ulStatus: upload speed in mbps - pingStatus: ping in ms - jitterStatus: jitter in ms - dlProgress: progress of the download test as a float 0-1 - ulProgress: progress of the upload test as a float 0-1 - pingProgress: progress of the ping/jitter test as a float 0-1 - testState: state of the test (-1=not started, 0=starting, 1=download test, 2=ping+jitter test, 3=upload test, 4=finished, 5=aborted) - clientIp: IP address of the client performing the test (and optionally ISP and distance) At the end of the test, the onend function will be called, with a boolean specifying whether the test was aborted or if it ended normally. The test can be aborted at any time with abort(). At the end of the test, it will move to state 4
4: test finished. You can run it again by calling start() if you want.

List of functions in the Speedtest class

getState()

Returns the state of the test: 0=adding settings, 1=adding servers, 2=server selection done, 3=test running, 4=done

setParameter(parameter,value)

Change one of the test settings from their defaults.

parameter: string with the name of the parameter that you want to set
value: new value for the parameter

Invalid values or nonexistant parameters will be ignored by the speedtest worker.

addTestPoint(server)

Add a test point (multiple points of test)

server: the server to be added as an object. Must contain the following elements:

{
    name: "User friendly name",
    server:"http://yourBackend.com/",   URL to your server. You can specify http:// or https://. If your server supports both, just write // without the protocol
    dlURL:"garbage.php"   path to garbage.php or its replacement on the server
    ulURL:"empty.php"   path to empty.php or its replacement on the server
    pingURL:"empty.php"   path to empty.php or its replacement on the server. This is used to ping the server by this selector
    getIpURL:"getIP.php"   path to getIP.php or its replacement on the server
}

Note that this will add mpot:true to the parameters sent to the speedtest worker.

addTestPoints(list)

Same as addTestPoint, but you can pass an array of servers

loadServerList(url,result)

Loads a list of servers from a JSON file pointed by the url.

The process is asynchronous and the result function will be called when it's done. If the request succeeded, an array containing the list of loaded servers will be passed to the function, otherwise null will be passed.

getSelectedServer()

Returns the selected server (multiple points of test)

setSelectedServer()

Manually selects one of the test points (multiple points of test)

selectServer(result)

Automatically selects a server from the list of added test points. The server with the lowest ping will be chosen. (multiple points of test)

The selector checks multiple servers in parallel (default: 6 streams) to speed things up if the list of servers is long.

The process is asynchronous and the passed result callback function will be called when it's done, then the test can be started.

start()

Starts the test.

Note (multiple points of test): the selected server will be added to the telemetry_extra string. If this string was already set, then telemetry_extra will be a JSON string containing both the server and the original string

During the test, the onupdate(data) callback function will be called periodically with data from the worker.
At the end of the test, the onend(aborted) function will be called with a boolean telling you if the test was aborted or if it ended normally.

abort()

Aborts the test while it's running.