From 82143fc35cdea0397c57932f6467465190de5749 Mon Sep 17 00:00:00 2001 From: Shahzad Date: Thu, 27 Feb 2025 11:52:44 +0100 Subject: [PATCH] update docs --- docs/src/api/class-apirequestcontext.md | 26 ++++--- ...-workers-experimental-network-events-js.md | 3 + packages/playwright-client/types/types.d.ts | 78 ++++++++++++++++--- packages/playwright-core/src/client/events.ts | 4 +- packages/playwright-core/types/types.d.ts | 78 ++++++++++++++++--- .../apirequestcontext-network-event.spec.ts | 12 +-- 6 files changed, 157 insertions(+), 44 deletions(-) diff --git a/docs/src/api/class-apirequestcontext.md b/docs/src/api/class-apirequestcontext.md index ab286b3163..d84c8a335c 100644 --- a/docs/src/api/class-apirequestcontext.md +++ b/docs/src/api/class-apirequestcontext.md @@ -120,18 +120,6 @@ with sync_playwright() as p: assert await response.body() == '{"status": "ok"}' ``` -## event: APIRequestContext.apiRequest -- argument: <[APIRequestEvent]> - -Emitted when a request is issued from any pages created through this context. -The [APIRequestEvent] object is read-only. - -## event: APIRequestContext.apiRequestFinished -- argument: <[APIRequestFinishedEvent]> - -Emitted when a request finishes successfully after downloading the response body. For a successful response, the -sequence of events is `request` and `requestfinished`. - ## method: APIRequestContext.createFormData * since: v1.23 * langs: csharp @@ -927,3 +915,17 @@ Returns storage state for this request context, contains current cookies and loc - `indexedDB` ? Defaults to `true`. Set to `false` to omit IndexedDB from snapshot. + +## event: APIRequestContext.apiRequest +* since: v1.51 +- argument: <[APIRequestEvent]> + +Emitted when a request is issued from any requests created through this context. +The [APIRequestEvent] object is read-only. + +## event: APIRequestContext.apiRequestFinished +* since: v1.51 +- argument: <[APIRequestFinishedEvent]> + +Emitted when a request finishes in any requests created through this context. The +sequence of events is `apirequest` and `apirequestfinished` diff --git a/docs/src/service-workers-experimental-network-events-js.md b/docs/src/service-workers-experimental-network-events-js.md index 43f32d7e61..50a59dfa83 100644 --- a/docs/src/service-workers-experimental-network-events-js.md +++ b/docs/src/service-workers-experimental-network-events-js.md @@ -67,6 +67,9 @@ Additionally, any network request made by the **Page** (including its sub-[Frame * [`method: Request.serviceWorker`] will be set to `null`, and [`method: Request.frame`] will return the [Frame] * [`method: Response.fromServiceWorker`] will return `true` (if a Service Worker's fetch handler was registered) +Any requests made by **APIRequestContext** will have +* [`event: APIRequestContext.apiRequest`] and its corresponding event ([`event: BrowserContext.apiRequestFinished`]) + Many Service Worker implementations simply execute the request from the page (possibly with some custom caching/offline logic omitted for simplicity): ```js title="transparent-service-worker.js" diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts index 7328793c2e..d5f746ad23 100644 --- a/packages/playwright-client/types/types.d.ts +++ b/packages/playwright-client/types/types.d.ts @@ -19,7 +19,6 @@ import { Readable } from 'stream'; import { ReadStream } from 'fs'; import { Protocol } from './protocol'; import { Serializable, EvaluationArgument, PageFunction, PageFunctionOn, SmartHandle, ElementHandleForTag, BindingSource } from './structs'; -import {APIRequestEvent, APIRequestFinishedEvent} from "playwright-core/lib/server/fetch"; type PageWaitForSelectorOptionsNotHidden = PageWaitForSelectorOptions & { state?: 'visible'|'attached'; @@ -17849,6 +17848,72 @@ export interface APIRequest { * `APIRequestContext` object will have its own isolated cookie storage. */ export interface APIRequestContext { + /** + * Emitted when a request is issued from any requests created through this context. The [APIRequestEvent] object is + * read-only. + */ + on(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Emitted when a request finishes in any requests created through this context. The sequence of events is + * `apirequest` and `apirequestfinished` + */ + on(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Emitted when a request is issued from any requests created through this context. The [APIRequestEvent] object is + * read-only. + */ + addListener(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Emitted when a request finishes in any requests created through this context. The sequence of events is + * `apirequest` and `apirequestfinished` + */ + addListener(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Emitted when a request is issued from any requests created through this context. The [APIRequestEvent] object is + * read-only. + */ + prependListener(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Emitted when a request finishes in any requests created through this context. The sequence of events is + * `apirequest` and `apirequestfinished` + */ + prependListener(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + /** * Sends HTTP(S) [DELETE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request and returns its * response. The method will populate request cookies from the context and update context cookies from the response. @@ -18666,17 +18731,6 @@ export interface APIRequestContext { }>; [Symbol.asyncDispose](): Promise; - - /** - * Emitted when a request is issued from API request context. The event will be emitted after the request is issued - */ - on(event: 'apiRequest', listener: (request: APIRequestEvent) => any): this; - - /** - * Emitted when a request finishes successfully after downloading the response body. For a successful response, the - * sequence of events is `request`, `response` and `requestfinished`. - */ - on(event: 'apiRequestfinished', listener: (request: APIRequestFinishedEvent) => any): this; } /** diff --git a/packages/playwright-core/src/client/events.ts b/packages/playwright-core/src/client/events.ts index de5b0a67a6..47d804c823 100644 --- a/packages/playwright-core/src/client/events.ts +++ b/packages/playwright-core/src/client/events.ts @@ -51,8 +51,8 @@ export const Events = { }, APIRequestContext: { - APIRequest: 'apiRequest', - APIRequestFinished: 'apiRequestfinished', + APIRequest: 'apirequest', + APIRequestFinished: 'apirequestfinished', }, BrowserServer: { diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 7328793c2e..d5f746ad23 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -19,7 +19,6 @@ import { Readable } from 'stream'; import { ReadStream } from 'fs'; import { Protocol } from './protocol'; import { Serializable, EvaluationArgument, PageFunction, PageFunctionOn, SmartHandle, ElementHandleForTag, BindingSource } from './structs'; -import {APIRequestEvent, APIRequestFinishedEvent} from "playwright-core/lib/server/fetch"; type PageWaitForSelectorOptionsNotHidden = PageWaitForSelectorOptions & { state?: 'visible'|'attached'; @@ -17849,6 +17848,72 @@ export interface APIRequest { * `APIRequestContext` object will have its own isolated cookie storage. */ export interface APIRequestContext { + /** + * Emitted when a request is issued from any requests created through this context. The [APIRequestEvent] object is + * read-only. + */ + on(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Emitted when a request finishes in any requests created through this context. The sequence of events is + * `apirequest` and `apirequestfinished` + */ + on(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. + */ + once(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Emitted when a request is issued from any requests created through this context. The [APIRequestEvent] object is + * read-only. + */ + addListener(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Emitted when a request finishes in any requests created through this context. The sequence of events is + * `apirequest` and `apirequestfinished` + */ + addListener(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + removeListener(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Removes an event listener added by `on` or `addListener`. + */ + off(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + + /** + * Emitted when a request is issued from any requests created through this context. The [APIRequestEvent] object is + * read-only. + */ + prependListener(event: 'apirequest', listener: (aPIRequestEvent: APIRequestEvent) => any): this; + + /** + * Emitted when a request finishes in any requests created through this context. The sequence of events is + * `apirequest` and `apirequestfinished` + */ + prependListener(event: 'apirequestfinished', listener: (aPIRequestFinishedEvent: APIRequestFinishedEvent) => any): this; + /** * Sends HTTP(S) [DELETE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request and returns its * response. The method will populate request cookies from the context and update context cookies from the response. @@ -18666,17 +18731,6 @@ export interface APIRequestContext { }>; [Symbol.asyncDispose](): Promise; - - /** - * Emitted when a request is issued from API request context. The event will be emitted after the request is issued - */ - on(event: 'apiRequest', listener: (request: APIRequestEvent) => any): this; - - /** - * Emitted when a request finishes successfully after downloading the response body. For a successful response, the - * sequence of events is `request`, `response` and `requestfinished`. - */ - on(event: 'apiRequestfinished', listener: (request: APIRequestFinishedEvent) => any): this; } /** diff --git a/tests/library/apirequestcontext-network-event.spec.ts b/tests/library/apirequestcontext-network-event.spec.ts index 6f8c6f1da6..c0acb9f946 100644 --- a/tests/library/apirequestcontext-network-event.spec.ts +++ b/tests/library/apirequestcontext-network-event.spec.ts @@ -20,7 +20,7 @@ import { APIRequestEvent, APIRequestFinishedEvent } from 'playwright-core/src/se it('APIRequestContext.Events.Request', async ({ context, server }) => { const requests: APIRequestEvent[] = []; - context.request.on('apiRequest', request => { + context.request.on('apirequest', request => { requests.push(request); }); await context.request.fetch(server.EMPTY_PAGE); @@ -38,7 +38,7 @@ it('APIRequestContext.Events.RequestFinished', async ({ context, server }) => { const finishedRequests: APIRequestFinishedEvent[] = []; - context.request.on('apiRequestfinished', request => finishedRequests.push(request)); + context.request.on('apirequestfinished', request => finishedRequests.push(request)); await context.request.fetch(server.EMPTY_PAGE); const request = finishedRequests[0]; @@ -49,11 +49,11 @@ it('APIRequestContext.Events.RequestFinished', async ({ context, server }) => { it('should fire events in proper order', async ({ context, server }) => { const events: string[] = []; - context.request.on('apiRequest', () => events.push('apiRequest')); - context.request.on('apiRequestfinished', () => events.push('apiRequestfinished')); + context.request.on('apirequest', () => events.push('apirequest')); + context.request.on('apirequestfinished', () => events.push('apirequestfinished')); await context.request.fetch(server.EMPTY_PAGE); expect(events).toEqual([ - 'apiRequest', - 'apiRequestfinished' + 'apirequest', + 'apirequestfinished' ]); });