DOCSEARCHbyAlgolia
Submit Docs

browsertime

repository·main·Indexed 20 days ago

https://github.com/sitespeedio/browsertime

A Node.js-based performance measurement engine used to collect deep web performance metrics, including page load times, visual metrics (LCP, SpeedIndex), and HAR files. It supports simulating complex user journeys via NodeJS scripting, testing on Android devices via ADB, and local latency simulation using WebPageReplay. Browsertime is the core engine behind sitespeed.io and is used by Mozilla for Firefox performance testing.

Tokens
44.3K
Snippets
170
Records
201
Agent score
70%

What's inside browsertime

  1. Simulate user journeys with Browsertime scripting

    main
    Browsertime allows you to simulate complex user journeys by writing custom scripts in NodeJS. Instead of just measuring a single page load, you can script entire flows—including navigation, clicks, and form submissions—to capture realistic performance metrics and visual data for every step of a user's interaction with a web application.

  2. How Browsertime works

    main

    Browsertime uses Selenium NodeJS to drive browsers. The process follows these steps:

    1. Starts the browser.
    2. Loads the target URL.
    3. Executes configurable JavaScript to collect performance metrics.
    4. Collects a HAR (HTTP Archive) file.

    HAR Generation Details:

    • Firefox: Uses the HAR Export Trigger.
    • Chrome: Uses Chrome-HAR to parse the timeline log and generate the HAR file.

  3. Test on Android devices

    main

    Browsertime supports Chrome and Firefox on Android for collecting SpeedIndex, HAR, and video.

    Prerequisites:

    1. Install adb.
    2. Prepare your phone for debugging.
    3. (Optional) Use gnirehtet if you need to set custom connectivity/throttling.

    Command: Use the --chrome.android.package flag to specify the Chrome package name on the device. You can also enable --video and --visualMetrics.

    $ browsertime --chrome.android.package com.android.chrome https://www.sitespeed.io --video --visualMetrics

  4. Use WebPageReplay for local latency simulation

    main

    The Browsertime Docker container includes WebPageReplay, which allows you to replay a page locally to eliminate server latency and find front-end regressions.

    Workflow:

    1. Start script in record mode.
    2. Browsertime accesses the URL once to record.
    3. WebPageReplay switches to replay mode.
    4. Browsertime accesses the URL multiple times from the local replay.

    Configuration:

    • Set the environment variable REPLAY=true to enable this functionality.
    • Set LATENCY=<ms> to define the simulated latency.
    • Use --cap-add=NET_ADMIN in Docker to allow network manipulation.

    Example (Chrome):

    docker run --cap-add=NET_ADMIN --rm -v "$(pwd)":/browsertime -e REPLAY=true -e LATENCY=100 sitespeedio/browsertime:20.0.0 https://en.wikipedia.org/wiki/Barack_Obama

  5. Install Browsertime via NodeJS or Docker

    main

    You can install Browsertime globally via npm or run it using a Docker container.

    NodeJS Installation: Install the package globally using npm and then run the browsertime command followed by a URL.

    Docker Installation: Run the sitespeedio/browsertime image. It is recommended to mount your current working directory to /browsertime inside the container to persist results.

    # NodeJS
npm install -g browsertime
browsertime https://example.com

# Docker
docker run --rm -v "$(pwd)":/browsertime sitespeedio/browsertime https://www.sitespeed.io/

  7. Record Video and Speed Index

    main

    To record video and calculate SpeedIndex, it is recommended to use the official Browsertime Docker container, as it includes all necessary dependencies for VisualMetrics.

    By default, the video includes a timer showing when metrics occur. You can disable this using the --video.addTimer false flag.

    # Example of disabling the video timer
browsertime https://example.com --video --video.addTimer false

  8. Get started with Browsertime scripting

    main

    To begin scripting user journeys, you should use NodeJS and familiar JavaScript syntax. For practical implementation, refer to the official tutorials and examples provided by sitespeed.io.

    Key capabilities include:

    • User Journey Simulation: Scripting flows from navigation to form submissions.
    • Performance Metrics Collection: Gathering load times and visual metrics for each step in a script.
    • NodeJS Integration: Using standard JavaScript and robust libraries to control the browser.

  9. Configure Android and iOS testing in Engine

    main

    The Engine supports automated mobile device testing via the following configuration patterns:

    Android

    If isAndroidConfigured(options) is true, the engine will:

    • Initialize the Android device.
    • Handle gnirehtet for internet connectivity if enabled.
    • Manage battery temperature limits via androidBatteryTemperatureLimit and androidBatteryTemperatureMaxTries.
    • Support rooted devices via androidRooted.
    • Execute pre-test actions like androidPretestPowerPress or androidPretestPressHomeButton.

    iOS Simulator

    If options.safari.useSimulator is true, the engine will:

    • Attempt to open Simulator.app via Xcode.
    • Locate the specific device using options.safari.deviceUDID.
    • Run tests on the identified simulator.

  10. Use the Wait class to wait for browser conditions

    main

    The Wait class provides methods to pause execution until specific conditions are met in the browser, such as elements appearing, becoming visible, or JavaScript conditions being satisfied. This is useful for handling asynchronous page loads and dynamic content during performance testing scripts.

    Common wait strategies include:

    • Element presence/visibility: Waiting for elements via ID, XPath, or CSS selectors.
    • Unified selectors: Using a single run() method with prefixed strings (e.g., id:myId, xpath://div).
    • JavaScript conditions: Waiting for a specific JS expression to evaluate to a truthy value.
    • Page state: Waiting for the page to complete its loading lifecycle.
    • Time-based: Pausing for a fixed duration.
    // Example of using different wait strategies
await commands.wait.bySelector('.my-class', 5000);
await commands.wait.byTime(1000);
await commands.wait.byPageToComplete();

  11. Capture Layout Shift (CLS) screenshots

    main

    When screenshotLS is enabled, Browsertime attempts to identify layout shifts using the PerformanceObserver API. It runs a script to highlight the shifted elements on the page before capturing the screenshot.

    To use this, ensure screenshotLS is set to true. You can customize the highlight appearance using screenshotLSColor and screenshotLSLimit (the threshold for what constitutes a shift).

  12. How the Click command handles element interaction

    main

    The Click command implements a robust interaction strategy to ensure scripts don't fail due to common web element issues:

    1. Selenium Actions API: It first attempts to use the Selenium Actions API to generate real OS-level mouse events. This moves the pointer to the center of the element's bounding box and clicks.
    2. Visibility Check: If an element is not displayed (e.g., display:none), it immediately falls back to a JavaScript click() to avoid silent failures where the click lands at (0,0).
    3. Fallback to JavaScript: If the Actions API fails (due to overlays, pointer-events:none, or other interactability issues), the command catches the error and attempts a JavaScript-based click (arguments[0].click()).

    This multi-layered approach ensures that performance scripts can interact with elements even if they are temporarily obscured or not perfectly interactable via standard mouse events.