Cloudflare Speedtest

@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.

Installation

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

npm i @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 })

Attributes

Methods

Notification Events

Measurement config

The specific measurements to be performed by the test engine (and their sequence) can be customized using the measurements config option. This should be an array of objects, each with a type field, plus additional fields specific to that measurement type.

The default set of measurements that is performed by the engine is:

[
  { type: 'latency', numPackets: 1 }, // initial latency estimation
  { type: 'download', bytes: 1e5, count: 1, bypassMinDuration: true }, // initial download estimation
  { type: 'latency', numPackets: 20 },
  { type: 'download', bytes: 1e5, count: 9 },
  { type: 'download', bytes: 1e6, count: 8 },
  { type: 'upload', bytes: 1e5, count: 8 },
  { type: 'packetLoss', numPackets: 1e3, responsesWaitTime: 3000 },
  { type: 'upload', bytes: 1e6, count: 6 },
  { type: 'download', bytes: 1e7, count: 6 },
  { type: 'upload', bytes: 1e7, count: 4 },
  { type: 'download', bytes: 2.5e7, count: 4 },
  { type: 'upload', bytes: 2.5e7, count: 4 },
  { type: 'download', bytes: 1e8, count: 3 },
  { type: 'upload', bytes: 5e7, count: 3 },
  { type: 'download', bytes: 2.5e8, count: 2 }
]

Here are the fields available per measurement type:

latency

download / upload

Each of these measurement sets are bound to a specific file size. The engine follows a ramp-up methodology per direction (download or upload). Whenever there are multiple measurement sets (with increasing file sizes) for a direction, the engine will keep on performing them until it reaches the condition specified by bandwidthMinRequestDuration, at which point further sets in the same direction are ignored.

packetLoss

Packet loss is measured by submitting a set of UDP packets to a WebRTC TURN server in a round-trip fashion, and determining how many packets do not arrive. The submission of these packets can be done in a batching method, in which there's a sleep time in between batches.

Results object

An instance object used to access the results of the speedtest measurements. The following methods are available on this object: