Skip to content

How-to Guides

This section provides practical, step-by-step guides for common tasks you might want to perform with Surfmeter Automator. These guides are designed to be quick and easy to follow, linking to more detailed reference documentation where necessary.

How to Measure the Quality of Netflix Streams?

Measuring Netflix quality involves defining a specific study in your configuration and potentially providing credentials.

  1. Define the Netflix Study: You need a study definition in your publicConfig.json file with "type": "VIDEO" and "subject": "netflix_trailer". Refer to the Public Config Reference and the guide on Changing the Configuration for details on editing the configuration file.

    Example publicConfig.json entry:

    {
  "id": "STUDY_NETFLIX_TRAILER",
  "type": "VIDEO",
  "subject": "netflix_trailer",
  "params": {
    "duration": 120, // measure for 120 seconds
    "timeout": 60,   // allow 60 seconds for setup
    "video": {
      "src": "https://www.netflix.com/tudum/videos/part-1-and-2-recap-money-heist", // Example
      "contentType": "trailer"
    },
    "playMode": "normal"
  }
}

  2. Run the Study: Once the study is defined, use the startStudy command with the defined study ID.

    ./surfmeter-automator-headless startStudy --studyId STUDY_NETFLIX_TRAILER

    docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless startStudy --studyId STUDY_NETFLIX_TRAILER

    For more details on running studies, see Running Studies.

    When it's done, you can find the results in the command-line output. Also, the data will be visible in our Surfmeter Dashboard.

How to Run Video and Speedtest in Parallel?

Automator allows running certain types of studies concurrently, like a browser-based video test and a native speed test.

  1. Ensure Studies are Defined: Make sure you have both study types defined in your publicConfig.json, for example, STUDY_YOUTUBE (VIDEO type) and STUDY_SPEEDTEST (native, e.g. ooklaspeedtest). See Changing the Configuration if needed.

    {
    "version": 1,
    "studies": [
        {
            "id": "STUDY_YOUTUBE",
            "type": "VIDEO",
            "subject": "youtube",
            "params": {
                "duration": 120,
                "timeout": 60,
                "video": {
                    "src": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
                    "contentType": "feature"
                }
            }
        },
        {
            "id": "STUDY_SPEEDTEST",
            "subject": "ooklaspeedtest",
            "type": "NETWORK"
        }
    ]
}

  2. Run startStudy with Multiple IDs: Provide the --studyId option multiple times in a single startStudy command.

    ./surfmeter-automator-headless startStudy --studyId STUDY_YOUTUBE --studyId STUDY_SPEEDTEST

    docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless startStudy --studyId STUDY_YOUTUBE --studyId STUDY_SPEEDTEST

    Limitation

    You currently cannot run two browser-based studies (like two different video studies or two website studies) in parallel. However, combining a browser study with one or more native studies (like ping, dns, native speedtest) is supported.

    Refer to Running Studies for more information.

How to Orchestrate a Lighthouse Test for 10 Different Websites?

You can measure multiple websites, including running Google Lighthouse tests on them, using a WEBSITE_GROUP study.

  1. Install Lighthouse: Ensure Google Lighthouse is installed globally via npm, as Automator uses the Lighthouse CLI. See the Setup guide.

    npm install -g lighthouse

  2. Define the Website Group Study: Edit your publicConfig.json (see Changing the Configuration). Specify the list of URLs.

    Example publicConfig.json entry:

    {
  "id": "STUDY_TOP10_LIGHTHOUSE",
  "type": "WEB",
  "subject": "lighthouse",
  "params": {
    "urls": [
      "https://www.google.com",
      "https://www.youtube.com",
      "https://www.facebook.com",
      "https://www.wikipedia.org",
      "https://www.amazon.com",
      "https://www.reddit.com",
      "https://www.yahoo.com",
      "https://www.twitter.com",
      "https://www.instagram.com",
      "https://www.linkedin.com"
    ],
    "timeout": 60 // Timeout per website
  }
}

  3. Run the Study: Use the startStudy command with the ID you defined.

    ./surfmeter-automator-headless startStudy --studyId STUDY_TOP10_LIGHTHOUSE

    docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless startStudy --studyId STUDY_TOP10_LIGHTHOUSE

    See Running Studies and Available Studies for more details.

How to Record the Screen and Produce a PCAP File?

Automator can simultaneously record the screen using ffmpeg and capture network packets using tcpdump during a study.

  1. Install Prerequisites:

    • FFmpeg: Ensure ffmpeg is installed and accessible. See Screen Recording.
    • tcpdump: Ensure tcpdump is installed and Automator has the necessary permissions to run it. See Tcpdump for more details. (Both are pre-installed and configured in the Docker image).

  2. Run startStudy with Flags: Use the --enableScreenRecording and --enableTcpDump flags when starting your study.

    ./surfmeter-automator-headless startStudy \
    --studyId STUDY_YOUTUBE \
    --enableScreenRecording \
    --enableTcpDump

    docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless startStudy \
    --studyId STUDY_YOUTUBE \
    --enableScreenRecording \
    --enableTcpDump

  3. Optional: Specify Output Directories: By default, recordings and PCAP files are saved to a temporary directory. You can specify persistent locations using:

    • --screenRecordingDir /path/to/videos/
    • --tcpDumpDir /path/to/pcaps/

    See Screen Recording and Special Features for more options, and check the Command Reference.