Network & Mocking

Inspect network traffic, mock API responses, and test offline behavior.

Inspect network requests

requests prints a numbered list of the requests made since the page loaded. Static resources that succeeded (images, fonts, stylesheets, scripts) are hidden by default to keep the list short.

playwright-cli requests                      # fetch/XHR and anything that failed
playwright-cli requests --static             # include successful static resources
playwright-cli requests --filter="/api/.*"   # only URLs matching this regexp
playwright-cli requests --clear              # clear the log

$ playwright-cli requests --filter="/api/"
# 1. [GET] https://api.example.com/users => [200] OK
# 2. [POST] https://api.example.com/users/create => [201] Created
# 3. [GET] https://api.example.com/prefs => [FAILED] net::ERR_ABORTED
#
# Note: 14 static requests not shown, run with --static option to see them.

Inspect a single request

Use the number from requests:

Command	Description
request <index>	Full details — request headers and body, response headers and body
request-headers <index>	Request headers only
request-body <index>	Request body only
response-headers <index>	Response headers only
response-body <index>	Response body only

playwright-cli request 2
playwright-cli response-body 2
playwright-cli response-body 2 --filename=users.json

All five accept --filename to write the result to a file instead of returning it as text. response-body inlines textual bodies and saves binary ones to a file, printing the path.

Mock API responses

playwright-cli route <pattern> [options]

Option	Description
--status=<code>	HTTP status code (default: 200)
--body=<text>	Response body (text or JSON string)
--content-type=<type>	Content-Type header of the mocked response
--header="<name>: <value>"	Header to add to the outgoing request (repeatable)
--remove-header=<names>	Comma-separated header names to strip from the request

A route either fulfills or rewrites. Passing --body or --status fulfills the request with a mock response and the page never reaches the network. Passing only --header / --remove-header lets the request continue to the real server with modified headers.

Mock an API endpoint

playwright-cli route "**/api/users" \
  --body='[{"name":"Alice"},{"name":"Bob"}]' \
  --content-type=application/json

Test error handling

playwright-cli route "**/api/data" --status=500
playwright-cli route "**/api/data" --status=503

Block resources

playwright-cli route "**/*.jpg" --status=404
playwright-cli route "**/analytics/**" --status=204

Rewrite request headers

# strip credentials from every request
playwright-cli route "**/*" --remove-header=cookie,authorization

# add a header to API calls
playwright-cli route "**/api/**" --header="X-Debug: 1"

Manage routes

playwright-cli route-list               # list active routes
playwright-cli unroute "**/api/users"   # remove specific route
playwright-cli unroute                  # remove all routes

URL patterns

**/api/users           - match this path on any origin
**/api/*/details       - wildcard segment
**/*.{png,jpg,jpeg}    - match file extensions
**/search?q=*          - match query parameters

Conditional mocking with code

For complex scenarios -- delays, conditional responses, or request body inspection -- use run-code:

playwright-cli run-code "async (page) => {
  await page.route('**/api/users', async route => {
    const body = route.request().postDataJSON();
    if (body.role === 'admin') {
      await route.fulfill({
        body: JSON.stringify({ permissions: ['read', 'write', 'delete'] })
      });
    } else {
      await route.fulfill({
        body: JSON.stringify({ permissions: ['read'] })
      });
    }
  });
}"

Workflow: testing error handling

# 1. Mock the API to return 503
playwright-cli route "**/api/users" --status=503

# 2. Reload to trigger the error
playwright-cli reload

# 3. Verify the error page
playwright-cli snapshot
# - heading "Something went wrong" [level=1]
# - button "Retry" [ref=e5]

# 4. Screenshot the error state
playwright-cli screenshot --filename=error-state.png

# 5. Remove mock and retry
playwright-cli unroute
playwright-cli click e5
playwright-cli snapshot
# - heading "Users" [level=1]

Test offline mode

playwright-cli network-state-set offline   # go offline
playwright-cli reload                      # page shows offline state
playwright-cli snapshot
# - heading "No internet connection" [level=1]

playwright-cli network-state-set online    # restore connection
playwright-cli reload                      # page loads normally