How should Chrome Headless arguments be passed?

[tollmanz]

Context

The goal of this project is to provide a simple CLI for generating performance timelines. At a minimum, it should provide the same options that the Chrome DevTools interface provides; however, we should aim to make this project more powerful by exposing additional options. These options can be passed to Puppeteer or the Chrome Headless client for extending the capabilities of the tool.

For example, the Chrome DevTools UI allows you to select different CPU throttling rates:

In Perf Timeline, I want to do the same; however, I'm conflicted about how this should be done. As of the initial commit, I use the following args to configure a CPU slow down of 4x:

perf-timeline generate \
  https://www.wired.com \
  --setCPUThrottlingRate \
  --rate 4

I use these exact terms to mirror the names used by Chrome Headless. My intent was to keep the same interface that you might use if you were coding this yourself. These values would then be used like this (not actual code, but shows how to access Chrome Headless directly):

const setCPUThrottlingRate = setCPUThrottlingRateFromCLI;
const rate = rateFromCLI;

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  if (setCPUThrottlingRate) {
    await page._client.send('Emulation.setCPUThrottlingRate', { rate });
  }

  await browser.close();
})();

The Problem

Currently, I allow direct access to Chrome Headless for CPU throttling and network emulation. These are only two categories of config. I am concerned that it may be an unnecessary burden on the CLI to provide args for the plethora of Chrome Headless args. I don't want to be in a place where this project dictates which args are acceptable and unacceptable.

Possible Solution

I'm thinking of changing the interface to allow for two things:

1. Convenience configuration for common sets of configs that match Chrome DevTools UI, as well as other useful groups
2. Allow an all-purpose --chrome-commands option that is parsed and passed to Chrome Headless

Regarding 1, I'd expose named configs that map to sets of Chrome Headless args. Something like:

# Slowdown the CPU
perf-timeline generate \
  https://www.wired.com \
  --cpu-slowdown 4

# Throttle the network
perf-timeline generate \
  https://www.wired.com \
  --network slow-3g

# Mobile Emulation
perf-timeline generate \
  https://www.wired.com \
  --cpu-slowdown 4 \
  --network slow-3g

# Match Lighthouse Speeds
perf-timeline generate \
  https://www.wired.com \
  --profile lighthouse

Note that to currently emulate a Lighthouse run, you need to do:

perf-timeline generate \
  https://www.wired.com \
  --emulate-network-conditions \
  --latency 150 \
  --upload-throughput 0.75 \
  --download--throughput 1.6 \
  --setCPUThrottlingRate \
  --rate 4  

Of course, with this added convenience comes the loss of control. To ensure that those who wish to control everything, I'd expose a more advanced option to further config Chrome Headless.

For 2, I would give the ability to do something like this:

perf-timeline generate \
  https://www.wired.com \
  --chrome-commands="Network.emulateNetworkConditions:latency=150,uploadThroughPut=0.75,downloadThroughput=1.6;Emulate.setCPUThrottlingRate:rate=4"

I'm not entirely sure that this would be the final form of the argument, but you should get the idea.

Questions

• What do you think of the current interface?
• What do you think of the proposed directions?

[tollmanz]

The current interface's days are numbered. Really starting to hate typing this out:

  --emulate-network-conditions \
  --latency 150 \
  --upload-throughput 0.75 \
  --download--throughput 1.6 \
  --setCPUThrottlingRate \
  --rate 4