DOCSEARCHbyAlgolia
Submit Docs

Flashlight Performance Tool

website·Indexed 33 days ago

https://docs.flashlight.dev

A performance measurement tool for Android apps, including a CLI and cloud service (flashlight.dev) for measuring app start performance and TTI. It supports React Native, integrates with Maestro for e2e tests, and provides a standalone reporter via the @perf-profiler/reporter package for custom scripts and CI integrations.

Tokens
5.5K
Snippets
33
Records
43
Agent score
62%

What's inside Flashlight

  1. Install Flashlight CLI on macOS, Linux, and Windows

    Install the Flashlight CLI using the provided curl script. For macOS users with arm64 (Apple Silicon) architecture, Rosetta must be installed first if it is not already present.
    # Install Rosetta for macOS arm64 (if needed)
softwareupdate --install-rosetta --agree-to-license

# Install Flashlight CLI
curl https://get.flashlight.dev | bash

  2. Install Flashlight CLI on macOS, Linux, and Windows

    Install the Flashlight CLI using the provided installation script. For macOS users with arm64 (Apple Silicon) architecture, Rosetta must be installed first to ensure compatibility.
    # Install Rosetta for macOS arm64 (Silicon) if not already installed
softwareupdate --install-rosetta --agree-to-license

# Install Flashlight CLI
curl https://get.flashlight.dev | bash

  3. Understand JS FPS in React Native

    JS FPS (Frames Per Second) measures the performance of the JavaScript thread in React Native. If JS FPS drops to 0, the app becomes unresponsive because the JS thread is blocked by expensive calculations or heavy tasks, preventing user interactions (like button clicks) from being processed until the task completes.

  4. Understand the device environment for flashlight.dev tests

    flashlight.dev executes the flashlight test command by running Maestro tests on real, lower-end hardware hosted on AWS Device Farm. By default, these tests are executed on a Samsung A15 to ensure performance is validated on a device representative of a lower-end user experience.

  5. Install Flashlight CLI on macOS, Linux, and Windows

    Install the Flashlight CLI using the provided curl script. For macOS users with arm64 (Apple Silicon) architecture, Rosetta must be installed first to ensure compatibility.
    # Install Rosetta for macOS arm64 (if not already installed)
softwareupdate --install-rosetta --agree-to-license

# Install Flashlight CLI
curl https://get.flashlight.dev | bash

  6. Measure app start performance using flashlight.dev cloud

    To get an app start performance score and Time to Interactive (TTI) measurement via the flashlight.dev cloud service, follow these steps:

    1. Upload your APK to app.flashlight.dev.
    2. Define the TTI trigger: Enter a string of text that appears on the screen once the app has successfully started. Flashlight uses this text to determine when the app is interactive. The text does not need to be an exact match of the full string (e.g., if the app displays "Hello world", entering "world" is sufficient).
    3. Wait for the report: Performance reports are sent via email (typically within ~10 minutes, depending on the queue). If the test fails, a video of the attempt will be provided for debugging.

  7. Measure JS thread performance using Flashlight

    Flashlight tracks JS thread CPU usage, which is inversely correlated with JS FPS: 0% CPU usage represents maximum JS FPS, while 100% CPU usage results in 0 JS FPS. To optimize performance, ensure the JS thread does not appear in the 'Processes with high CPU usage' section and that the average FPS remains close to 60. When using flashlight measure or flashlight report, the JS thread is preselected on the third graph for analysis.
    # Use these commands to analyze JS thread performance
flashlight measure
flashlight report

  8. Measure Android app CPU usage using ADB top

    You can measure the CPU consumption of production Android apps without installing SDKs by using the top command via the Android Debug Bridge (ADB). This is possible because Android is based on Linux. Note that CPU consumption can exceed 100% because each CPU core accounts for 100% (e.g., a 9-core device has a maximum of 900%).
    # Display CPU stats every 1 second
adb shell top -d 1

  9. Execute setup steps before performance measurements

    Use the --beforeAll flag to specify a Maestro test file that should run once before the actual performance measurement begins. This is useful for tasks like accepting cookies or logging into an app. The steps in the beforeAll file are not included in the performance metrics.
    flashlight cloud --app example.apk \
  --test start.yml \
  --duration 10000 \
  --beforeAll beforeAll.yml

  10. Debug Flashlight tests locally using Maestro

    When cloud tests fail and the cause is unclear, you can reproduce the failure locally on a physical device using Maestro. This allows you to use Maestro Studio to verify if the wording passed to Flashlight matches what Maestro expects or to run the flow manually. To accurately reproduce the cloud environment's 'blank state', include a clearState command at the beginning of your flow to wipe local device data.
    appId: your.app.id
---
- clearState
- launchApp
- tapOn: "Text on the screen"

  11. Configure Android device connectivity for Flashlight CI

    To run Flashlight in CI, the environment must be connected to a physical Android device. Using an emulator on CI is discouraged as it is typically too slow and will not accurately reproduce real-world performance. Because the profiler requires full adb access, only specific device cloud providers are compatible:

    • AWS Device Farm
    • Saucelabs (requires Enterprise plan and Virtual USB enabled)
    • Genymotion Cloud (Note: uses emulators, which may not provide accurate performance data)

    Alternatively, the flashlight.dev cloud version is available in open beta.

  12. Create a project in Flashlight Cloud

    To create a project in the Flashlight Cloud console:

    1. Click on "Projects" in the top-right menu, then click the "+" button.
    2. Add user emails to the project. Note that users must have already created an account before they can be added.
    3. Once created, note the project id, as it is required for CLI integration.