Telescope

@cloudflare/telescope — A cross-browser performance testing CLI and Node.js library built on Playwright.

What it collects

When you run the agent, it will load the page in the browser you chose and apply any special parameters you have provided. By default, it will store results for the test in a /results directory. Each test gets its own folder with the date prefixed, followed by a unique ID.

Note: Telescope injects an x-telescope-id header into every outgoing request during testing. This header carries a unique ID used to correlate timing data with HAR entries. It is sent to the target server and will be visible in the saved HAR file.

Inside the test folder, the following files are added:

• console.json - Console output from the page to look for warnings, JS errors, etc
• a video file showing the page load progression
• metrics.json - A collection of timing metrics collected from the browser during page load
• pageload.har - A har file of the page load
• resources.json - The resource timing API data for the page
• screenshot.png - A screenshot of the final page load
• /filmstrip - A collection of screenshots during the page load that could be used for a filmstrip

Parameters

A full list of parameters can be printed to the terminal by running telescope --help. Running telescope (or npx @cloudflare/telescope) with no arguments also prints the help message.

The URL to test can be provided either as a positional argument or via the -u/--url option:

telescope https://example.com
telescope -u https://example.com

If the URL is provided without a scheme, one is prepended automatically:

telescope example.com         # tests https://example.com
telescope localhost:3000      # tests http://localhost:3000  (localhost defaults to http)
telescope 127.0.0.1:8080      # tests http://127.0.0.1:8080  (loopback defaults to http)
telescope app.localhost       # tests http://app.localhost

Localhost-equivalent hosts (localhost, *.localhost, and the 127.0.0.0/8 loopback range) default to http:// since local dev servers rarely have TLS configured. All other scheme-less hosts default to https://. An explicit scheme always wins (telescope https://localhost:3000 stays https).

Only http:// and https:// URLs are supported. Other schemes (file://, ftp://, about:blank, data:..., mailto:..., etc.) are rejected with an error.

Here's what's currently supported:

Arguments:
  url                           URL to run tests against. Can also be provided via -u/--url.

Options:
  -u, --url <url>               URL to run tests against
  -b, --browser <browser_name>  Browser to run tests with (choices: "chrome", "chrome-beta", "canary", "edge", "safari", "firefox", default: "chrome")
  -h, --headers <object>        Any custom headers to apply to requests
  -c, --cookies <object>        Any custom cookies to apply
  -f, --flags <string>          A comma separated list of Chromium flags to launch Chrome with. See: https://peter.sh/experiments/chromium-command-line-switches/
  --agentExtra <string>         A string to append to the end of the default User-Agent. Takes precedence over --userAgent option.
  --device '<string>'           Device to use device emulation (viewport size, DPR, touch events); devices are based on the Playwright device list (see https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json)
  --blockDomains <domains...>   A comma separated list of domains to block
  --block <substrings...>       A comma-delimited list of urls to block (based on a substring match)
  --delay <object>              An object mapping request regexes to response delays. Example: '{".css$": 2000, ".js$": 5000}'
  --delayUsing <string>         Method to use to delay responses (choices: "continue", "fulfill", default: "continue")
  --firefoxPrefs <object>       Any Firefox User Preferences to apply (Firefox only). Example: '{"network.trr.mode": 2}'
  --cpuThrottle <int>           CPU throttling factor
  --connectionType <string>     Network connection type. By default, no throttling is applied. (choices: "cable", "dsl", "4g", "3g", "3gfast", "3gslow", "2g", "fios", default: false)
  --width <int>                 Viewport width, in pixels (default: "1366")
  --height <int>                Viewport height, in pixels (default: "768")
  --frameRate <int>             Filmstrip frame rate, in frames per second (default: 1)
  --disableJS                   Disable JavaScript (default: false)
  --debug                       Output debug lines (default: false)
  --auth <object>               Basic HTTP authentication (Expects: {"username": "", "password": ""}) (default: false)
  --timeout <int>               Maximum time (in milliseconds) to wait for test to complete (default: 30000)
  --html                        Generate HTML report (default: false)
  --openHtml                    Open HTML report in browser (requires --html) (default: false)
  --list                        Generate list of results in HTML (default: false)
  --overrideHost <object>       Override the hostname of a URI with another host (Expects: {"example.com": "example.org"})
  --userAgent <string>          Set the browsers User-Agent
  --zip                         Zip the results of the test into the results directory. (default: false)
  --uploadUrl <string>          Upload results to URL. Must be a valid URL if provided. (default: null)
  --dry                         Dry run (do not run test, just save config and cleanup) (default: false)
  --help                        display help for command

Browser Support

Telescope uses Playwright to control and manage individual browser engines:

telescope -u https://www.example.com -b firefox

And supports the following browsers:

• Chromium
  • Chrome - chrome
  • Chrome Beta - chrome-beta
  • Chrome Canary - canary
  • Edge - edge
• Safari/Webkit - safari
• Firefox - firefox

Custom Timeout

You can set a custom timeout by passing the desired timeout in milliseconds using the --timeout parameter. Defaults to 30000, or 30 seconds.

telescope -u https://www.example.com -b chrome --timeout 50000

HTML Report Generation

Browser Support ✅ Edge ✅ Chrome ✅ Safari ✅ Firefox

You can generate an HTML report of your test results by passing the --html parameter. To automatically open the report in your default browser after generation, add the --openHtml flag.

Generate HTML report

telescope -u https://example.com -b chrome --html

Generate and automatically open HTML report

telescope -u https://example.com -b chrome --html --openHtml

Setting Custom Cookies

Browser support ✅ Edge ✅ Chrome 🚫 Safari ✅ Firefox

You can define custom cookies to be passed along to request when running your test using the -c or --cookies parameter.

Cookies must have a name and value passed. Optionally, you can also pass in either a URL or a domain and path. If none are passed, the script will default to using the test page url.

Set a custom cookie for all requests

telescope -u https://www.example.com -b chrome -c '{"name": "foo", "value": "bar"}'

Set multiple cookies for all requests

telescope -u https://www.example.com -b chrome -c '[{"name": "foo", "value": "bar"}, {"name": "foo2", "value": "bar2"}]'

Set a custom cookie for only a particular path

telescope -u https://www.example.com -b chrome -c '{"name": "foo", "value": "bar", "domain":"www.example.com", "path":"/optim"}'

Disabling JavaScript

Browser Support ✅ Edge ✅ Chrome ✅ Safari ✅ Firefox

You can run tests with JavaScript disabled to see the impact on performance by passing the --disableJS parameter like so:

telescope -u https://playwright.dev/ -b firefox --disableJS

Basic HTTP Authentication

Browser Support ✅ Edge ✅ Chrome ✅ Safari ✅ Firefox

To test sites protected with HTTP authentication, you can pass the --auth parameter. It expects an object with a username and password like so:

telescope -u https://newsletter.www.example.com/admin -b safari --auth '{"username": "username", "password": "password"}'

Host overrides

Browser Support ✅ Edge ✅ Chrome ✅ Safari ✅ Firefox (see note below)

To override hostnames during a test run, use the --overrideHost option with an object mapping between the host and how it should resolve to.

For example, you can cause requests to cdn.example.com to route to local web server running on port 8080 via:

telescope -u https://www.example.com -b firefox \
  --overrideHost '{"cdn.example.com": "127.0.0.1:8080"}'

Note: Firefox uses an HSTS preload list, which automatically upgrades requests prior to Playwright can intercept it. To work around this, you can disable the HSTS preload list with --firefoxPrefs:

telescope -u https://www.example.com -b firefox \
  --overrideHost '{"cdn.example.com": "127.0.0.1:8080"}' \
  --firefoxPrefs '{"network.stricttransportsecurity.preloadlist": false}'

Docker

Build and run telescope in a container:

# Build
docker compose build

# Run a test
docker compose run --rm telescope -u https://example.com -b chrome

# Run with network throttling
docker compose run --rm telescope -u https://example.com -b chrome --connectionType 3g

# Results are saved to ./results/

Supports: Chrome, Chrome Beta, Edge, Firefox, and Safari (WebKit).

Network Throttling Limitation

Network throttling (--connectionType) requires OS-level traffic shaping via the Linux ifb kernel module. This works on native Linux machines but does not work in Docker Desktop (Mac or Windows), because the Docker Desktop Linux VM does not include the required kernel module.

Installation

Quick start

npm install -g @cloudflare/telescope
telescope https://example.com

The postinstall script automatically runs npx playwright install to download Chrome, Firefox, and Safari (~700MB, may take 2–5 minutes).

After npm install -g, the telescope command is on your PATH and can be invoked directly without npx. Verify with which telescope (Unix) or where telescope (Windows).

If you see command not found: telescope, your global npm bin directory isn't on PATH. Add it with:

export PATH="$(npm config get prefix)/bin:$PATH"

From source

From the repo root:

npm install
npm run build -w packages/telescope
npm link                          # registers the `telescope` command globally

Or from packages/telescope/ directly:

cd packages/telescope
npm install
npm run build
npm link

Browsers

Chrome, Firefox, and Safari

Telescope's postinstall script automatically runs npx playwright install to install chrome, firefox, and safari. The download is ~700MB and may take 2–5 minutes.

If you skipped the postinstall (e.g. npm install --ignore-scripts), run it manually:

npx playwright install

Microsoft Edge and Chrome-beta

To install Microsoft Edge or Chrome Beta playwright requires root privileges and will not automatically install them, all you have to do that is to run npx playwright install msedge chrome-beta from the command line (and provide root password).

Chrome Canary

Chrome Canary must be manually installed, please download and install from: https://www.google.com/chrome/canary/

ffmpeg

Telescope uses ffmpeg to process the video and generate filmstrip images. You will need to have it installed on your machine.

For MacOS you can use homebrew to install it:

brew install ffmpeg

Programmatic Usage

You can run telescope from within a Node.js script:

import { launchTest } from '@cloudflare/telescope';

const result = await launchTest({
  url: 'https://example.com',
  browser: 'chrome',
  width: 1920,
  height: 1080,
  timeout: 60000,
});

if (result.success) {
  console.log(`Test completed: ${result.testId}`);
  console.log(`Results saved to: ${result.resultsPath}`);
} else {
  console.error(`Test failed: ${result.error}`);
}

All CLI options are supported as object properties. See Parameters section for available options.

Contributing To This Project

Commands below can be run from packages/telescope/ directly, or from the repo root using workspace shortcuts (see root README.md).

Running Automated Tests

To run automated code tests in this project, you can use the following command:

npm run test

Using Specific Browsers

You can run tests with specific browsers by setting the BROWSERS environment variable. For example, to run tests with Chrome and Firefox, you can run:

BROWSERS=chrome,firefox npm run test

The same browser can be listed more than once; each occurrence will run as a separate test pass. This can be useful for debugging side effects of running multiple tests on the same browser or just long tests.

Note: BROWSERS environment variable is ignored when running in CI.

Running Tests In Headless Mode

You can run tests in headless mode by setting the HEADLESS environment variable to true. For example:

HEADLESS=true npm run test

Our CI Pipeline

Our CI pipeline is set up to run tests on every push to the repository so you can see results in your pull request.

At this point, to limit the length of the tests and (to simplify compatibility with GitHub Actions) it runs tests in headless mode on firefox only.

If you want to run the same configuration locally, you can run CI=true npm test. You can override the default headless CI mode by setting the HEADLESS environment variable to false. However, you can't override the set of browsers that the CI configuration runs (it will always run firefox only).