docs(websocket): add web socket examples (#5927)

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
+Most of the time, scripts will need to wait for a particular event to happen. Below are some of the typical event
-in the page. They are usually the preferred choice. Here is a few examples:
+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"));

docs/src/network.md

@@ -469,3 +469,46 @@ page.route("**/*", lambda route: route.abort() if route.request.resource_type ==
 - [`method: Route.abort`]
 
 <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/>