Support CPU and Network throttling

[ka3de]

Feature Description

CPU and network throttling are useful in order to emulate specific network conditions, for example in order to emulate a mobile connection speed when actually running in a faster connection.

See Lighthouse project documentation on throttling: https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md
See CDP APIs in order to throttle CPU and network.

Suggested Solution (optional)

No response

Already existing or connected issues / PRs (optional)

No response

Tasks

Beta Give feedback

1. Implement Network throttling -- Add throttleNetwork on page #1094
2. Implement CPU throttling -- Add throttleCPU on page #1095
3. Implement predefined network profiles -- Add predefined network profiles #1098
4. Update k6-docs -- Add page.throttleCPU and page.throttleNetwork docs k6-docs#1415
5. Update release notes -- Add CPU and Network throttling to release notes k6#3453
6. Update Type definitions -- Add CPU and Network Throttling definitions k6-DefinitelyTyped#19

[mdcruz]

I support this feature, and it would be great if we could prioritise this somehow 👍🏼

One strength of using lab data is the ability to run tests in a controlled environment. Currently, we can do this in k6 browser by setting the screen size or removing certain Chrome arguments, but not the ability to configure network throttling (e.g. from 5g to 4g). I want to be able to change my network connection to see how this impacts my web vital metrics.

[mdcruz]

Example on how Playwright can do it: microsoft/playwright#6038 (comment)

[ankur22]

We should look at existing tools and see how they've implemented the same feature. Playwright doesn't seem to support it as a dedicated API yet, but puppeteer does have dedicated APIs for both CPU and network. It's probably worth looking through any discussions in both tools to see whether there's any discussions around how to improve these APIs -- i'm most curious why playwright hasn't implemented it, there could be a valid reason for it.

[inancgumus]

@ankur22

i'm most curious why playwright hasn't implemented it, there could be a valid reason for it.

For the network throttling side:

Here's some info why Playwright lacks the feature: microsoft/playwright#8622 (comment):

We are prioritizing the features based on the upvotes, recency and activity in the issue thread. It looks like this issue only has a handful of upvotes, has not been touched recently and/or we lack sufficient feedback to act on it. We are closing issues like this one to keep our bug database maintainable. Please feel free to open a new issue and link this one to it if you think this is a mistake.

They also have a Route API that enables users to throttle requests. See: microsoft/playwright#19173 (comment).

And they allow users to send CDP messages: microsoft/playwright#6038 (comment).

[ankur22]

We have explored this feature and we're hoping to start work on it imminently.

We see value in implementing two new APIs to throttle the CPU and another to throttle the network. Many end users of websites are going to be on slower devices under poor network conditions, and to be able to test those conditions in a lab setting we need succinct APIs.

The idea is to (essentially) wrap the CDP APIs in order to throttle CPU and network with a javascript API on the page object. We considered adding them to the browserContext object (like we have done for setOffline), but we feel that an API with less restrictions and more flexibility within the same test (so allowing one page to react "normally" and another page to be throttled in the same test iteration) is likely going to cover more use cases.

The proposed API is as follows:

export interface Page{
  ...
  throttleCPU(profile: CPUProfile)
  
  throttleNetwork(profile: NetworkProfile)
}

export interface CPUProfile {
  // rate as a slowdown factor (1 is no throttle, 2 is 2x slowdown, etc).
  rate: number;
}

export interface NetworkProfile {
  // Minimum latency from request sent to response headers received (ms).
  latency: number;
  
  // Maximal aggregated download throughput (bytes/sec). -1 disables download throttling.
  download: number;
  
  // Maximal aggregated upload throughput (bytes/sec). -1 disables upload throttling.
  upload: number;
}

We will provide useful network profiles such as slow 3G and fast 3G. We won't be providing CPU profiles since this will depend on where the chrome instance is run on.

The CDP API lacks the support of throttling websocket connections (https://crbug.com/563644). We're unlikely to resolve this soon through our own implementation.

We welcome feedback on the decision we have made and comments to help fine tune the feature.

[inancgumus]

Closing this as completed. cc: @grafana/k6-browser