Telescope
A diagnostic, cross-browser performance testing agent
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. Each test generates:
console.json- Console output from the page (warnings, JS errors, etc)video.webm- Video showing the page load progressionmetrics.json- Timing metrics collected during page loadpageload.har- HAR file of the page loadresources.json- Resource timing API datascreenshot.png- Screenshot of the final page/filmstrip- Screenshots during page load for filmstrip view
Quick Start
npx @cloudflare/telescope -u https://example.com -b chromeCLI Parameters
| Flag | Description | Default |
|---|---|---|
-u, --url <url> |
URL to run tests against | required |
-b, --browser <name> |
Browser to run tests with. Choices: chrome, chrome-beta, canary, edge, safari, firefox |
chrome |
-h, --headers <object> |
Custom headers to apply to requests (JSON) | - |
-c, --cookies <object> |
Custom cookies to apply (JSON) | - |
-f, --flags <string> |
Comma-separated list of Chromium flags | - |
--blockDomains <domains...> |
Comma-separated list of domains to block | [] |
--block <substrings...> |
Comma-separated list of URL substrings to block | [] |
--firefoxPrefs <object> |
Firefox User Preferences (JSON, Firefox only) | - |
--cpuThrottle <int> |
CPU throttling factor | - |
--connectionType <string> |
Network throttling. Choices: cable, dsl, 4g, 3g, 3gfast, 3gslow, 2g, fios |
none |
--width <int> |
Viewport width in pixels | 1366 |
--height <int> |
Viewport height in pixels | 768 |
--frameRate <int> |
Filmstrip frame rate (fps) | 1 |
--disableJS |
Disable JavaScript | false |
--debug |
Output debug lines | false |
--auth <object> |
Basic HTTP authentication (JSON: {"username": "", "password": ""}) |
- |
--timeout <int> |
Maximum time in milliseconds to wait | 30000 |
--html |
Generate HTML report | false |
--openHtml |
Open HTML report in browser (requires --html) | false |
--zip |
Zip the results into the results directory | false |
Examples
Basic test
npx @cloudflare/telescope -u https://example.com -b chromeWith network throttling (3G)
npx @cloudflare/telescope -u https://example.com -b chrome --connectionType 3gCustom viewport
npx @cloudflare/telescope -u https://example.com -b chrome --width 1920 --height 1080With custom cookies
npx @cloudflare/telescope -u https://example.com -b chrome -c '{"name": "session", "value": "abc123"}'Generate ZIP for upload
npx @cloudflare/telescope -u https://example.com -b chrome --zipTest with JavaScript disabled
npx @cloudflare/telescope -u https://example.com -b firefox --disableJSHTTP Basic Auth
npx @cloudflare/telescope -u https://staging.example.com -b safari --auth '{"username": "user", "password": "pass"}'Installation
npm install @cloudflare/telescopeTelescope uses Playwright to control browsers. After installation, browsers are automatically installed via npx playwright install.
You'll also need ffmpeg for video processing:
brew install ffmpegSupported Browsers
Chrome
Chrome Beta
Chrome Canary
Firefox
Safari
Edge