PlaywrightPHP

Throttling

Simulate slower network conditions without making every browser test slower.

Throttling slows or shapes network traffic to expose loading states, timeout behavior, and performance regressions.

Use it sparingly. A slow network test is valuable when the product promise includes a loading, retry, offline, or degraded-network experience.

Mental model

Throttling changes the network environment. It is different from waiting. A wait observes a condition; throttling creates a slower condition for the page to handle.

php
use Playwright\Network\NetworkThrottling;

$context = Playwright::chromium();
$context->setNetworkThrottling(NetworkThrottling::slow3G());

$page = $context->newPage();

$page->goto('https://app.example.test/dashboard');

expect($page->getByRole('status'))->toContainText('Loading');

$context->disableNetworkThrottling();

Keep the throttling setup close to the test that needs it. A global slow network makes the whole suite expensive.

What to test

  • skeleton or loading states;
  • retry banners;
  • optimistic UI rollback;
  • timeout messages;
  • performance budgets under constrained conditions.

Use traces and network logs to prove the condition was applied.

Choose throttling or a server delay

Need Prefer
Prove loading UI appears under slow browser network throttling
Force one endpoint to respond slowly route or test server delay
Test retry after a failed API call routing
Measure product performance budget dedicated performance test

Throttling is useful for experience tests. It is not a replacement for deterministic backend fixtures.

When not to use it

Do not throttle the whole suite to make missing waits pass. Fix the wait or assertion.

Do not assert exact milliseconds on shared CI runners. Assert user-visible states and use traces or metrics for diagnosis.

Common pitfalls

  • Slowing the whole suite for one scenario.
  • Using throttling to hide missing waits.
  • Asserting exact timings on shared CI machines.
  • Forgetting that server-side delays and browser network throttling are different.
  • Keeping performance thresholds that no longer match the product budget.

Go next