Skip to main content

WebSocketRoute

每当使用 page.routeWebSocket() 或 browserContext.routeWebSocket() 设置 WebSocket 路由时，WebSocketRoute 对象都允许处理 WebSocket，就像实际服务器一样。

¥Whenever a WebSocket route is set up with page.routeWebSocket() or browserContext.routeWebSocket(), the WebSocketRoute object allows to handle the WebSocket, like an actual server would do.

模拟

¥Mocking

默认情况下，路由的 WebSocket 不会连接到服务器。这样，你就可以模拟通过 WebSocket 进行的整个通信。下面是一个使用 "response" 响应 "request" 的示例。

¥By default, the routed WebSocket will not connect to the server. This way, you can mock entire communcation over the WebSocket. Here is an example that responds to a "request" with a "response".

await page.routeWebSocket('wss://example.com/ws', ws => {
  ws.onMessage(message => {
    if (message === 'request')
      ws.send('response');
  });
});

由于我们没有在 WebSocket 路由处理程序中调用 webSocketRoute.connectToServer()，因此 Playwright 假定 WebSocket 将被模拟，并自动在页面内打开 WebSocket。

¥Since we do not call webSocketRoute.connectToServer() inside the WebSocket route handler, Playwright assumes that WebSocket will be mocked, and opens the WebSocket inside the page automatically.

以下是另一个处理 JSON 消息的示例：

¥Here is another example that handles JSON messages:

await page.routeWebSocket('wss://example.com/ws', ws => {
  ws.onMessage(message => {
    const json = JSON.parse(message);
    if (json.request === 'question')
      ws.send(JSON.stringify({ response: 'answer' }));
  });
});

拦截

¥Intercepting

或者，你可能希望连接到实际的服务器，但拦截中间的消息并修改或阻止它们。调用 webSocketRoute.connectToServer() 会返回一个服务器端 WebSocketRoute 实例，你可以向该实例发送消息或处理传入消息。

¥Alternatively, you may want to connect to the actual server, but intercept messages in-between and modify or block them. Calling webSocketRoute.connectToServer() returns a server-side WebSocketRoute instance that you can send messages to, or handle incoming messages.

下面是修改页面发送到服务器的一些消息的示例。从服务器发送到页面的消息保持不变，依赖于默认转发。

¥Below is an example that modifies some messages sent by the page to the server. Messages sent from the server to the page are left intact, relying on the default forwarding.

await page.routeWebSocket('/ws', ws => {
  const server = ws.connectToServer();
  ws.onMessage(message => {
    if (message === 'request')
      server.send('request2');
    else
      server.send(message);
  });
});

连接到服务器后，默认情况下，所有消息都会在页面和服务器之间转发。

¥After connecting to the server, all messages are forwarded between the page and the server by default.

但是，如果你在原始路由上调用 webSocketRoute.onMessage()，则从页面到服务器的消息将不再转发，而应由 handler 处理。

¥However, if you call webSocketRoute.onMessage() on the original route, messages from the page to the server will not be forwarded anymore, but should instead be handled by the handler.

类似地，在服务器端 WebSocket 上调用 webSocketRoute.onMessage() 将停止将消息从服​​务器转发到页面，handler 应该会处理它们。

¥Similarly, calling webSocketRoute.onMessage() on the server-side WebSocket will stop forwarding messages from the server to the page, and handler should take care of them.

以下示例在两个方向上阻止了一些消息。由于它在两个方向上都调用 webSocketRoute.onMessage()，因此根本没有自动转发。

¥The following example blocks some messages in both directions. Since it calls webSocketRoute.onMessage() in both directions, there is no automatic forwarding at all.

await page.routeWebSocket('/ws', ws => {
  const server = ws.connectToServer();
  ws.onMessage(message => {
    if (message !== 'blocked-from-the-page')
      server.send(message);
  });
  server.onMessage(message => {
    if (message !== 'blocked-from-the-server')
      ws.send(message);
  });
});

方法​

¥Methods

close​

Added in: v1.48 webSocketRoute.close

关闭 WebSocket 连接的一侧。

¥Closes one side of the WebSocket connection.

用法

¥Usage

await webSocketRoute.close();
await webSocketRoute.close(options);

参数

¥Arguments

可选 关闭代码。

¥Optional close code.

可选 关闭原因。

¥Optional close reason.

返回

¥Returns

connectToServer​

Added in: v1.48 webSocketRoute.connectToServer

默认情况下，路由的 WebSocket 不会连接到服务器，因此你可以模拟整个 WebSocket 通信。此方法连接到实际的 WebSocket 服务器，并返回服务器端 WebSocketRoute 实例，从而能够从服务器发送和接收消息。

¥By default, routed WebSocket does not connect to the server, so you can mock entire WebSocket communication. This method connects to the actual WebSocket server, and returns the server-side WebSocketRoute instance, giving the ability to send and receive messages from the server.

一旦连接到服务器：

¥Once connected to the server:

有关更多详细信息，请参阅顶部的示例。

¥See examples at the top for more details.

用法

¥Usage

webSocketRoute.connectToServer();

返回

¥Returns

onClose​

Added in: v1.48 webSocketRoute.onClose

允许处理 WebSocket.close。

¥Allows to handle WebSocket.close.

默认情况下，关闭连接的一侧（无论是在页面中还是在服务器上）都会关闭另一侧。但是，当设置 webSocketRoute.onClose() 处理程序时，闭包的默认转发被禁用，处理程序应该处理它。

¥By default, closing one side of the connection, either in the page or on the server, will close the other side. However, when webSocketRoute.onClose() handler is set up, the default forwarding of closure is disabled, and handler should take care of it.

用法

¥Usage

webSocketRoute.onClose(handler);

参数

¥Arguments

处理 WebSocket 闭包的函数。收到可选 关闭代码 和可选 关闭原因。

¥Function that will handle WebSocket closure. Received an optional close code and an optional close reason.

onMessage​

Added in: v1.48 webSocketRoute.onMessage

此方法允许处理 WebSocket 发送的消息，无论是从页面还是从服务器发送。

¥This method allows to handle messages that are sent by the WebSocket, either from the page or from the server.

在原始 WebSocket 路由上调用时，此方法处理从页面发送的消息。你可以通过使用 webSocketRoute.send() 响应这些消息来处理它们，将它们转发到 webSocketRoute.connectToServer() 返回的服务器端连接或执行其他操作。

¥When called on the original WebSocket route, this method handles messages sent from the page. You can handle this messages by responding to them with webSocketRoute.send(), forwarding them to the server-side connection returned by webSocketRoute.connectToServer() or do something else.

一旦调用此方法，消息就不会自动转发到服务器或页面 - 你应该通过调用 webSocketRoute.send() 手动执行此操作。有关更多详细信息，请参阅顶部的示例。

¥Once this method is called, messages are not automatically forwarded to the server or to the page - you should do that manually by calling webSocketRoute.send(). See examples at the top for more details.

再次调用此方法将用新方法覆盖处理程序。

¥Calling this method again will override the handler with a new one.

用法

¥Usage

webSocketRoute.onMessage(handler);

参数

¥Arguments

处理消息的函数。

¥Function that will handle messages.

send​

Added in: v1.48 webSocketRoute.send

向 WebSocket 发送消息。在原始 WebSocket 上调用时，将消息发送到页面。在 webSocketRoute.connectToServer() 的结果上调用时，将消息发送到服务器。有关更多详细信息，请参阅顶部的示例。

¥Sends a message to the WebSocket. When called on the original WebSocket, sends the message to the page. When called on the result of webSocketRoute.connectToServer(), sends the message to the server. See examples at the top for more details.

用法

¥Usage

webSocketRoute.send(message);

参数

¥Arguments

要发送的消息。

¥Message to send.

url​

Added in: v1.48 webSocketRoute.url

在页面中创建的 WebSocket 的 URL。

¥URL of the WebSocket created in the page.

用法

¥Usage

webSocketRoute.url();

返回

¥Returns