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.

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",
  "names": {
    "en_US": {
      "short": "Netflix Test",
      "long": "Netflix Trailer Test"
    }
  },
  "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"
  }
}

Run the Study: Once the study is defined, use the startStudy command with the defined study ID.
Native ExecutionDocker
./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.

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",
            "names": {
                "en_US": {
                    "short": "YouTube Test",
                    "long": "YouTube Test"
                }
            },
            "params": {
                "duration": 120,
                "timeout": 60,
                "video": {
                    "src": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "contentType": "feature"
                }
            }
        },
        {
            "id": "STUDY_SPEEDTEST",
            "subject": "ooklaspeedtest",
            "type": "NETWORK",
            "names": {
                "en_US": {
                    "short": "Ookla Speedtest",
                    "long": "Ookla Speedtest test"
                }
            },
            "native": {
                "enabled": true
            }
        }
    ]
}

Run startStudy with Multiple IDs: Provide the --studyId option multiple times in a single startStudy command.
Native ExecutionDocker
./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.

Install Lighthouse: Ensure Google Lighthouse is installed globally via npm, as Automator uses the Lighthouse CLI. See the Setup guide.
```
npm install -g lighthouse
```

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",
  "names": {
    "en_US": {
      "short": "Top 10 Lighthouse",
      "long": "Lighthouse Test for Top 10 Websites"
    }
  },
  "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
  },
  "native": {
    "enabled": true
  }
}

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

Native ExecutionDocker

./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.

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 Special Features - Packet Captures. (Both are pre-installed and configured in the Docker image).

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

Native ExecutionDocker

./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

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.