From cc265fe1eb2be0053c5120f5a2e109ec3ae4a888 Mon Sep 17 00:00:00 2001
From: Pavel Feldman <pavel.feldman@gmail.com>
Date: Wed, 24 Mar 2021 08:17:59 +0800
Subject: [PATCH] docs(websocket): add web socket examples (#5927)

---
 docs/src/events.md  | 15 ++++++++-------
 docs/src/network.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/docs/src/events.md b/docs/src/events.md
index 5b44fd2055..0f6d24b8ac 100644
--- a/docs/src/events.md
+++ b/docs/src/events.md
@@ -3,7 +3,7 @@ id: events
 title: "Events"
 ---
 
-Playwright allows listening to various types of events happening in the browser, such
+Playwright allows listening to various types of events happening in the web page, such
 as network requests, creation of child pages, dedicated workers etc. There are several
 ways to subscribe to such events:
 
@@ -11,10 +11,10 @@ ways to subscribe to such events:
 
 ## Waiting for event
 
-There is a number of methods which wait for a particular condition or an event happening
-in the page. They are usually the preferred choice. Here is a few examples:
+Most of the time, scripts will need to wait for a particular event to happen. Below are some of the typical event
+awaiting patterns.
 
-Waiting for a request with a specified url:
+Wait for a request with the specified url:
 
 ```js
 const [request] = await Promise.all([
@@ -46,7 +46,7 @@ with page.expect_request("**/*logo*.png") as first:
 print(first.value.url)
 ```
 
-Waiting for popup window:
+Wait for popup window:
 
 ```js
 const [popup] = await Promise.all([
@@ -80,7 +80,8 @@ popup.value.goto("https://wikipedia.org")
 
 ## Adding/removing event listener
 
-Playwright supports traditional language mechanisms to subscribe and unsubscribe from events:
+Sometimes, events happen in random time and instead of waiting for them, they need to be handled.
+Playwright supports traditional language mechanisms for subscribing and unsubscribing from the events:
 
 ```js
 page.on('request', request => console.log(`Request sent: ${request.url()}`));
@@ -135,7 +136,7 @@ page.goto("https://www.openstreetmap.org/")
 
 ## Adding one-off listeners
 
-If only next event needs to be handled, there is a convinience API for some of the events:
+If certain event needs to be handled once, there is a convenience API for that:
 
 ```js
 page.once('dialog', dialog => dialog.accept("2021"));
diff --git a/docs/src/network.md b/docs/src/network.md
index 2fdd0a4221..a0f1a1fd6f 100644
--- a/docs/src/network.md
+++ b/docs/src/network.md
@@ -468,4 +468,47 @@ page.route("**/*", lambda route: route.abort() if route.request.resource_type ==
 - [`method: BrowserContext.route`]
 - [`method: Route.abort`]
 
-<br/>
\ No newline at end of file
+<br/>
+
+## WebSockets
+
+Playwright supports [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) inspection out of the
+box. Every time WebSocket is created, [`event: Page.webSocket`] event is fired. This event contains the [WebSocket]
+instance for further web socket frames inspection:
+
+```js
+page.on('websocket', ws => {
+  console.log(`WebSocket opened: ${ws.url()}>`);
+  ws.on('framesent', event => console.log(event.payload));
+  ws.on('framereceived', event => console.log(event.payload));
+  ws.on('close', () => console.log('WebSocket closed'));
+});
+```
+
+```java
+page.onWebSocket(ws -> {
+  log("WebSocket opened: " + ws.url());
+  ws.onFrameSent(frameData -> log(frameData.text()));
+  ws.onFrameReceived(frameData -> log(frameData.text()));
+  ws.onClose(ws1 -> log("WebSocket closed"));
+});
+```
+
+```python
+def on_web_socket(ws):
+    print(f"WebSocket opened: {ws.url}")
+    ws.on("framesent", lambda payload: print(payload))
+    ws.on("framereceived", lambda payload: print(payload))
+    ws.on("close", lambda payload: print("WebSocket closed"))
+
+page.on("websocket", on_web_socket)
+```
+
+### API reference
+- [WebSocket]
+- [`event: Page.webSocket`]
+- [`event: WebSocket.frameSent`]
+- [`event: WebSocket.frameReceived`]
+- [`event: WebSocket.close`]
+
+<br/>