A diagnostic, cross-browser performance testing agent.
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.
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 loadpageload.har- A har file of the page loadresources.json- The resource timing API data for the pagescreenshot.png- A screenshot of the final page load/filmstrip- A collection of screenshots during the page load that could be used for a filmstrip
A full list of parameters can be printed to the terminal by running npx . --help. Here's what's currently supported:
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.
--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
Telescope uses Playwright to control and manage individual browser engines:
npx . -u https://www.example.com -b firefox
And supports the following browsers:
- Chromium
- Chrome -
chrome - Chrome Beta -
chrome-beta - Chrome Canary -
canary - Edge -
edge
- Chrome -
- Safari/Webkit -
safari - Firefox -
firefox
You can set a custom timeout by passing the desired timeout in milliseconds using the --timeout parameter. Defaults to 30000, or 30 seconds.
npx . -u https://www.example.com -b chrome --timeout 50000
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.
npx . -u https://example.com -b chrome --html
npx . -u https://example.com -b chrome --html --openHtml
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.
npx . -u https://www.example.com -b chrome -c '{"name": "foo", "value": "bar"}'
npx . -u https://www.example.com -b chrome -c '[{"name": "foo", "value": "bar"}, {"name": "foo2", "value": "bar2"}]'
npx . -u https://www.example.com -b chrome -c '{"name": "foo", "value": "bar", "domain":"www.example.com", "path":"/optim"}'
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:
npx . -u https://playwright.dev/ -b firefox --disableJS
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:
npx . -u https://newsletter.www.example.com/admin -b safari --auth '{"username": "username", "password": "password"}'
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
# Results are saved to ./results/Supports: Chrome, Chrome Beta, Edge, Firefox, and Safari (WebKit).
The container runs as an unprivileged user by default. If you need network throttling (the --connectionType option), run the container as root:
docker compose run --rm --user root telescope --connectionType 3G https://example.comAfter checking out the code, you need to install all the dependencies and build the project:
npm install
npm run build
Telescope will automatically run npx playwright install to install chrome, firefox, and safari.
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 must be manually installed, please download and install from: https://www.google.com/chrome/canary/
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
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.
To run automated code tests in this project, you can use the following command:
npm run test
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.
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 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).