Playwright sees every request a page makes: you can mock it, wait for it, or send your own.
Snippets alias Playwright.{Page, Route, ...}.
Mocking with routes
A route intercepts the requests whose URL matches, and its handler decides what happens to each:
Page.route!(page, "**/api/users", &Route.fulfill!(&1, json: [%{name: "Ada"}]))
Page.route!(page, "**/*.{png,jpg}", &Route.abort!/1)A handler of two arguments also gets the Request. It must fulfill, continue, abort or
fallback the route; a request whose handler does none of these hangs:
Page.route!(page, "**/api/**", fn route, request ->
case Request.method(request) do
"DELETE" -> Route.fulfill!(route, status: 403, json: %{error: "forbidden"})
_ -> Route.continue!(route, headers: Map.put(Request.headers(request), "x-test", "1"))
end
end)To change a real response, fetch it and fulfill with the result:
Page.route!(page, "**/api/users", fn route ->
response = Route.fetch!(route)
users = APIResponse.json!(response)
Route.fulfill!(route, response: response, json: users ++ [%{name: "Grace"}])
end)- The pattern is a glob, a
Regexor a function of the URL, which gets aURI(&(&1.path == "/api/users")); withbase_url, a path such as"/api/users"is resolved against it. - When several routes match, the one added last runs;
Route.fallback!/2hands the request to the one before. BrowserContext.route/4covers every page of the context, including a popup's first request.times: 1routes once;Page.unroute/3removes a route.
Like listeners, handlers run in their own processes; see the Concurrency guide.
Delaying a response
To hold a response back, say to see a loading state, the handler starts a process that waits and then fulfills, and returns at once (JS awaits a timer in the handler):
Page.route!(page, "**/api/users", fn route ->
Task.start(fn ->
Process.sleep(500)
Route.fulfill!(route, json: [%{name: "Grace"}])
end)
end)The request completes when the task fulfills, and the page's other requests and your calls go on
meanwhile. A Process.sleep/1 or receive in the handler itself stalls every page on that
connection (Concurrency); the task can receive
instead, to wait for the test.
Replaying a HAR
A HAR file records requests and responses. Record one against the real backend with
update: true (the file is written when the context closes), then replay it in tests:
BrowserContext.route_from_har!(context, "test/fixtures/api.har", url: "**/api/**", update: true)
# ... use the app, then
BrowserContext.close!(context)BrowserContext.route_from_har!(context, "test/fixtures/api.har", url: "**/api/**")Requests not in the HAR are aborted; not_found: :fallback sends them on to other routes or the
network. Page.route_from_har/3 does the same for one page.
Waiting for requests and responses
Start the wait before the action that sends the request, as for any event:
response =
Page.expect_response!(page, "**/api/users", fn ->
Page.get_by_role(page, :button, name: "Reload") |> Locator.click!()
end)
assert Response.status(response) == 200
assert [%{"name" => _} | _] = Response.json!(response)expect_request!/4 waits for the request instead, and both take a predicate in place of the URL:
&(Response.url(&1) =~ "/api/" and Response.status(&1) >= 400). To watch all traffic, listen to
:request, :response, :request_finished or :request_failed with
Page.on/3.
WebSockets
Page.route_web_socket/3 intercepts the WebSockets whose
URL matches. Without WebSocketRoute.connect_to_server/1
the handler is the server; with it, frames pass between the page and the server, and
WebSocketRoute.on_message/2 on either side takes over that direction. To delay the server's
frames to the page:
Page.route_web_socket!(page, "**/ws", fn ws ->
server = WebSocketRoute.connect_to_server(ws)
WebSocketRoute.on_message(server, fn message ->
Task.start(fn ->
Process.sleep(500)
WebSocketRoute.send(ws, message)
end)
end)
end)A LiveView's socket, at the default socket "/live" path, is "**/live/websocket*". The
on_message/2 handler hands each frame to a process that waits, and returns at once: a
Process.sleep/1 in the handler itself stalls every page on that connection, as blocking the
event loop does in JS (see
Concurrency). Each frame gets its own timer. For a
strict order, send each frame with its deadline, taken as it arrives
(System.monotonic_time(:millisecond) + 500), to one process that sleeps only for the rest of
each deadline before it sends the frame on.
A frame that never arrives:
The route must come before the page opens the socket: route, then
goto.The route's pattern must match the socket's URL (
ws://orwss://, its path and query).on_message/2stops the forwarding of its side: send on the frames it doesn't handle withWebSocketRoute.send/2. Withoutconnect_to_server/1, nothing reaches the server.Watch the frames on the wire, as upstream's network guide does:
require Logger Page.on(page, :web_socket, fn ws -> Logger.info("WebSocket opened: #{WebSocket.url(ws)}") WebSocket.on(ws, :frame_sent, &Logger.info("sent: #{inspect(&1.payload)}")) WebSocket.on(ws, :frame_received, &Logger.info("received: #{inspect(&1.payload)}")) WebSocket.on(ws, :close, fn _ -> Logger.info("WebSocket closed") end) end)A routed socket's frames on the wire are those between the page and the server: a frame the handler holds back shows as received, though the page doesn't have it yet. A socket mocked without
connect_to_server/1never reaches the wire, so it has no:web_socketevent and no trace entry: log its frames in youron_message/2handler and next to yourWebSocketRoute.send/2calls instead.A trace with
snapshots: true(asPlaywright.Test's) has each socket on the wire and its frames in its Network tab (Debugging and CI).
API testing
Playwright.APIRequestContext sends HTTP requests without a browser, to test an API or to set
up data before a UI test:
request =
Playwright.instance()
|> Playwright.request()
|> APIRequest.new_context!(
base_url: "http://localhost:4000",
extra_http_headers: %{"authorization" => "Bearer #{token}"}
)
response = APIRequestContext.post!(request, "/api/issues", data: %{title: "Broken link"})
Expect.to_be_ok!(response)
assert %{"title" => "Broken link"} = APIResponse.json!(response)
APIRequestContext.dispose!(request)data: sends a map as JSON; form: and multipart: send forms, params: the query string.
Responses are kept until dispose!/1, so in ExUnit create the context in setup and dispose of
it in on_exit/1.
BrowserContext.request/1 (or
Page.request/1) is the context's own API client: it shares
cookies with the pages, so a request made there is logged in as the page is, and cookies it gets
back show up in the pages.
More: network, mock APIs (with WebSockets), API testing.