cloudflare/speedtest

cloudflare/speedtest

Description: Component to perform network speed tests against Cloudflare's edge network

Language: TypeScript

License: MIT

Stars: 698

Forks: 77

Open issues: 21

Created: 2023-03-02T12:15:24Z

Pushed: 2026-06-09T15:51:06Z

Default branch: main

Fork: no

Archived: no

README:

Cloudflare Speedtest

[![NPM package][npm-img]][npm-url] [![Build Size][build-size-img]][build-size-url] [![NPM Downloads][npm-downloads-img]][npm-downloads-url]

@cloudflare/speedtest is a JavaScript module to measure the quality of a client’s Internet connection. It's the measurement engine that powers the Cloudflare speedtest measurement application available at https://speed.cloudflare.com.

The module performs test requests against the Cloudflare edge network and relies on the PerformanceResourceTiming browser api to extract timing results. The network connection is characterized by items such as download/upload bandwidth, latency and packet loss.

Please note that measurement results are collected by Cloudflare on completion for the purpose of calculating aggregated insights regarding Internet connection quality.

Warning: The public TURN server for Packet Loss testing is deprecated and will be discontinued soon. Read the [packetLoss](#packetloss) section for more information.

Installation

Add this package to your package.json by running this in the root of your project's directory:

npm install @cloudflare/speedtest

Simple Usage

import SpeedTest from '@cloudflare/speedtest';

new SpeedTest().onFinish = results => console.log(results.getSummary());

API reference

SpeedTest is a JavaScript Class and should be instantiated with the new keyword. It's not required to pass a config object, as all items have default values.

Instantiation

new SpeedTest({ configOptions })

| Config option | Description | Default | | --- | --- | :--: | | autoStart: *boolean* | Whether to automatically start the measurements on instantiation. | true | | downloadApiUrl: *string* | The URL of the API for performing download GET requests. | https://speed.cloudflare.com/__down | | uploadApiUrl: *string* | The URL of the API for performing upload POST requests. | https://speed.cloudflare.com/__up | | turnServerUri: *string* | The URI of the TURN server used to measure packet loss. | turn.cloudflare.com:3478 | | turnServerCredsApiUrl: *string* | A URI that returns TURN server credentials. Expects a JSON response with username and credential keys. | - | | turnServerUser: *string* | The username for the TURN server credentials. | - | | turnServerPass: *string* | The password for the TURN server credentials. | - | | measurements: *array* | The sequence of measurements to perform by the speedtest engine. See [below](#measurement-config) for the specific syntax of this option. || | measureDownloadLoadedLatency: *boolean* | Whether to perform additional latency measurements simultaneously with download requests, to measure loaded latency (during download). | true | | measureUploadLoadedLatency: *boolean* | Whether to perform additional latency measurements simultaneously with upload requests, to measure loaded latency (during upload). | true | | loadedLatencyThrottle: *number* | Time interval to wait in between loaded latency requests (in milliseconds). | 400 | | bandwidthFinishRequestDuration: *number* | The minimum duration (in milliseconds) to reach in download/upload measurement sets for halting further measurements with larger file sizes in the same direction. | 1000 | | bandwidthAbortRequestDuration: *number* | The minimum duration (in milliseconds) to reach in download/upload measurement sets for aborting the test early | 0 (disabled) | | estimatedServerTime: *number* | If the download/upload APIs do not return a server-timing response header containing the time spent in the server, this fixed value (in milliseconds) will be subtracted from all time-to-first-byte calculations. | 10 | | latencyPercentile: *number* | The percentile (between 0 and 1) used to calculate latency from a set of measurements. | 0.5 | | bandwidthPercentile: *number* | The percentile (between 0 and 1) used to calculate bandwidth from a set of measurements. | 0.9 | | bandwidthMinRequestDuration: *number* | The minimum duration (in milliseconds) of a request to consider a measurement good enough to use in the bandwidth calculation. | 10 | | loadedRequestMinDuration: *number* | The minimum duration (in milliseconds) of a request to consider it to be loading the connection. | 250 | | loadedLatencyMaxPoints: *number* | The maximum number of data points to keep for loaded latency measurements. When more than this amount are available, the latest ones are kept. | 20 |

Attributes

| Attribute | Description | | --- | --- | | results: *[Results](#results-object)* | Getter of the current [test results](#results-object) object. May yield incomplete values if the test is still running. | | isRunning: *boolean* | Getter of whether the test engine is currently running. | | isFinished: *boolean* | Getter of whether the test engine has finished all the measurements, and the results are considered final. |

Methods

| Method | Description | | --- | --- | | play() | Starts or resumes the measurements. Does nothing if the engine is already running or is finished. | | pause() | Pauses the measurements. Does nothing if the engine is already paused or is finished. | | restart() | Clears the current results and restarts the measurements from the beginning. |

Notification Events

| Event Method | Arguments | Description | | --- | --- | --- | | onRunningChange | running: *boolean* | Invoked whenever the test engine starts or stops. The current state is included as a function argument. | | onResultsChange | { type: *string* } | Invoked whenever any item changes in the results, usually indicating the completion of a measurement. The type of measurement that changed is included as an info attribute in the function argument. | | onFinish | results: *[Results](#results-object)* | Invoked whenever the test engine finishes all the measurements. The final [results object](#results-object) is included as a function argument.…