Cloudflare Telescope

Why Cloudflare Telescope?

🌐

Cross-Browser Testing

Test performance across Chrome, Firefox, Safari, Edge, and their variants with a single command.

📊

Comprehensive Metrics

Collect detailed performance data including HAR files, screenshots, videos, and timing metrics.

⚡

Easy Setup

Run with npx - no manual installation. Dependencies install automatically on first run.

💎

Open Source

Free and open source under the Apache 2.0 License. Contributions welcome from the community.

How to Run a Test

Get started with Cloudflare Telescope by cloning the repository and running your first test.

Step 1: Clone the Repository

git clone https://github.com/cloudflare/telescope.git
cd telescope

Step 2: Install Dependencies

npm install

This will install Playwright and all required browser binaries (~700MB). This may take 2-5 minutes on first install.

For detailed installation requirements and troubleshooting, see the official installation guide.

Step 3: Run Your First Test

npx . -u https://example.com

With Custom Parameters

npx . -u https://example.com \
  -b firefox \
  --width 1920 \
  --height 1080 \
  --timeout 50000

Advanced Example with Network Throttling

npx . -u https://example.com \
  -b chrome \
  --connectionType 3g \
  --cpuThrottle 4 \
  --blockDomains ads.example.com,tracker.example.com

Testing with Custom Headers and Cookies

npx . -u https://example.com \
  -b edge \
  -h '{"Authorization": "Bearer token123"}' \
  -c '{"session": "abc123", "userId": "456"}'

Configuration Parameters

Cloudflare Telescope provides extensive configuration options to simulate various testing scenarios.

-u, --url <url>

URL to run tests against. This is the target website you want to analyze.

-b, --browser <browser>

Browser to test against. Options: chrome, chrome-beta, canary, edge, safari, firefox (default: chrome)

-h, --headers <object>

Custom headers to apply to requests. Useful for authentication or custom API testing.

-c, --cookies <object>

Custom cookies to apply. Test authenticated pages or user-specific scenarios.

--connectionType <string>

Network throttling. Options: cable, dls, 4g, 3g, 3gfast, 3gslow, 2g, fios (default: false)

--cpuThrottle <int>

CPU throttling factor to simulate slower devices. Higher values = more throttling.

--width / --height <int>

Viewport dimensions in pixels (default: 1366x768). Test responsive designs.

--blockDomains <domains...>

Block specific domains during testing. Useful for excluding ads or analytics.

--block <substrings...>

Block URLs based on substring match. More granular control than domain blocking.

--disableJS

Disable JavaScript execution. Test how your site performs without JS.

--timeout <int>

Maximum test duration in milliseconds (default: 30000). Prevent hanging tests.

--html

Generate an HTML report of the test results for easy viewing.

--auth <object>

Basic HTTP authentication credentials with username and password.

--frameRate <int>

Filmstrip frame rate in FPS (default: 1). Higher values = smoother filmstrips.

-f, --flags <string>

Comma-separated Chromium flags for advanced browser configuration.

--firefoxPrefs <object>

Firefox-specific user preferences (Firefox only).

What Telescope Collects

Each test generates comprehensive performance data stored in a dedicated results folder with unique identifiers.

🎬

Video Recording

Complete video showing page load progression from start to finish, perfect for visual analysis.

📸

Screenshots

Final page screenshot and filmstrip collection for frame-by-frame load analysis.

📈

Performance Metrics

Comprehensive timing metrics including FCP, LCP, TTI, and CLS collected from the browser.

🌐

HAR File

Complete network waterfall data in HAR format for detailed request analysis.

⚡

Resource Timing

Detailed Resource Timing API data for every asset loaded on the page.

🔍

Console Output

All console messages, warnings, and JavaScript errors captured during page load.

Results Structure

/results/
  └── 2025-10-26_unique-id-123/
      ├── console.json        # Console logs and errors
      ├── metrics.json        # Performance metrics
      ├── pageload.har        # Network waterfall
      ├── resources.json      # Resource timing data
      ├── screenshot.png      # Final screenshot
      ├── video.mp4          # Page load video
      └── /filmstrip/        # Frame-by-frame screenshots

Leading Contributors

Cloudflare Telescope is built and maintained by talented developers from around the world.

View All Contributors on GitHub

Want to Contribute?

Telescope is an open-source project and welcomes contributions from the community. Whether it's bug fixes, new features, documentation improvements, or testing across different platforms - all contributions are appreciated!

Contribute on GitHub