From 620e8547d41e714c6aac15cdbfb458a30ceaba54 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Mon, 21 Nov 2022 10:40:21 -0800 Subject: [PATCH] chore: generate usage: sections based on snippets (#18965) --- docs/src/api/class-accessibility.md | 2 + docs/src/api/class-android.md | 2 + docs/src/api/class-apirequestcontext.md | 8 +- docs/src/api/class-apiresponseassertions.md | 2 + docs/src/api/class-browser.md | 6 + docs/src/api/class-browsercontext.md | 16 ++ docs/src/api/class-browsertype.md | 6 + docs/src/api/class-electronapplication.md | 5 +- docs/src/api/class-elementhandle.md | 14 +- docs/src/api/class-frame.md | 33 ++- docs/src/api/class-jshandle.md | 4 +- docs/src/api/class-keyboard.md | 6 + docs/src/api/class-locator.md | 20 +- docs/src/api/class-locatorassertions.md | 40 +++ docs/src/api/class-page.md | 58 +++- docs/src/api/class-pageassertions.md | 8 + docs/src/api/class-playwrightassertions.md | 8 + docs/src/api/class-request.md | 8 + docs/src/api/class-route.md | 6 + docs/src/api/class-screenshotassertions.md | 4 + docs/src/api/class-selectors.md | 2 + docs/src/api/class-tracing.md | 4 + packages/playwright-core/types/types.d.ts | 277 +++++++++++++++++--- packages/playwright-test/types/test.d.ts | 54 ++++ 24 files changed, 541 insertions(+), 52 deletions(-) diff --git a/docs/src/api/class-accessibility.md b/docs/src/api/class-accessibility.md index 7230f05588..dce0b8cc85 100644 --- a/docs/src/api/class-accessibility.md +++ b/docs/src/api/class-accessibility.md @@ -58,6 +58,8 @@ The Chromium accessibility tree contains nodes that go unused on most platforms will discard them as well for an easier to process tree, unless [`option: interestingOnly`] is set to `false`. ::: +**Usage** + An example of dumping the entire accessibility tree: ```js diff --git a/docs/src/api/class-android.md b/docs/src/api/class-android.md index 88f003e331..67b96c331a 100644 --- a/docs/src/api/class-android.md +++ b/docs/src/api/class-android.md @@ -140,6 +140,8 @@ Prevents automatic playwright driver installation on attach. Assumes that the dr Launches Playwright Android server that clients can connect to. See the following example: +**Usage** + Server Side: ```js diff --git a/docs/src/api/class-apirequestcontext.md b/docs/src/api/class-apirequestcontext.md index 932b5e198c..4a5debdb14 100644 --- a/docs/src/api/class-apirequestcontext.md +++ b/docs/src/api/class-apirequestcontext.md @@ -188,9 +188,9 @@ discards all stored responses, and makes [`method: APIResponse.body`] throw "Res - returns: <[APIResponse]> Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update -context cookies from the response. The method will automatically follow redirects. +context cookies from the response. The method will automatically follow redirects. JSON objects can be passed directly to the request. -JSON objects can be passed directly to the request: +**Usage** ```js await request.fetch('https://example.com/api/createBook', { @@ -351,6 +351,8 @@ Sends HTTP(S) [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GE The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. +**Usage** + Request parameters can be configured with `params` option, they will be serialized into the URL search parameters: ```js @@ -535,6 +537,8 @@ Sends HTTP(S) [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/P The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. +**Usage** + JSON objects can be passed directly to the request: ```js diff --git a/docs/src/api/class-apiresponseassertions.md b/docs/src/api/class-apiresponseassertions.md index c045ae679f..b46565f0ad 100644 --- a/docs/src/api/class-apiresponseassertions.md +++ b/docs/src/api/class-apiresponseassertions.md @@ -74,6 +74,8 @@ The opposite of [`method: APIResponseAssertions.toBeOK`]. Ensures the response status code is within `200..299` range. +**Usage** + ```js await expect(response).toBeOK(); ``` diff --git a/docs/src/api/class-browser.md b/docs/src/api/class-browser.md index e77cbfaa83..bb516be613 100644 --- a/docs/src/api/class-browser.md +++ b/docs/src/api/class-browser.md @@ -108,6 +108,8 @@ The [Browser] object itself is considered to be disposed and cannot be used anym Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts. +**Usage** + ```js const browser = await pw.webkit.launch(); console.log(browser.contexts().length); // prints `0` @@ -173,6 +175,8 @@ If directly using this method to create [BrowserContext]s, it is best practice t and before calling [`method: Browser.close`]. This will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved. ::: +**Usage** + ```js (async () => { const browser = await playwright.firefox.launch(); // Or 'chromium' or 'webkit'. @@ -292,6 +296,8 @@ This API controls [Chromium Tracing](https://www.chromium.org/developers/how-tos You can use [`method: Browser.startTracing`] and [`method: Browser.stopTracing`] to create a trace file that can be opened in Chrome DevTools performance panel. +**Usage** + ```js await browser.startTracing(page, {path: 'trace.json'}); await page.goto('https://www.google.com'); diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index e4d1fbee89..82f9c4ec41 100644 --- a/docs/src/api/class-browsercontext.md +++ b/docs/src/api/class-browsercontext.md @@ -203,6 +203,8 @@ Emitted when new service worker is created in the context. Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [`method: BrowserContext.cookies`]. +**Usage** + ```js await browserContext.addCookies([cookieObject1, cookieObject2]); ``` @@ -247,6 +249,8 @@ Adds a script which would be evaluated in one of the following scenarios: The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`. +**Usage** + An example of overriding `Math.random` before the page loads: ```js browser @@ -336,6 +340,8 @@ Clears context cookies. Clears all permission overrides for the browser context. +**Usage** + ```js const context = await browser.newContext(); await context.grantPermissions(['clipboard-read']); @@ -415,6 +421,8 @@ BrowserContext, page: Page, frame: Frame }`. See [`method: Page.exposeBinding`] for page-only version. +**Usage** + An example of exposing page URL to all frames in all pages in the context: ```js @@ -639,6 +647,8 @@ If the [`param: callback`] returns a [Promise], it will be awaited. See [`method: Page.exposeFunction`] for page-only version. +**Usage** + An example of adding a `sha256` function to all pages in the context: ```js @@ -894,6 +904,8 @@ is enabled, every request matching the url pattern will stall unless it's contin [`method: BrowserContext.route`] will not intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting [`option: Browser.newContext.serviceWorkers`] to `'block'`. ::: +**Usage** + An example of a naive handler that aborts all image requests: ```js @@ -1170,6 +1182,8 @@ An object containing additional HTTP headers to be sent with every request. All Sets the context's geolocation. Passing `null` or `undefined` emulates position unavailable. +**Usage** + ```js await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667}); ``` @@ -1295,6 +1309,8 @@ Optional handler function used to register a routing with [`method: BrowserConte Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the context closes before the event is fired. Returns the event data value. +**Usage** + ```js const [page, _] = await Promise.all([ context.waitForEvent('page'), diff --git a/docs/src/api/class-browsertype.md b/docs/src/api/class-browsertype.md index a9b229b7db..99bff95ded 100644 --- a/docs/src/api/class-browsertype.md +++ b/docs/src/api/class-browsertype.md @@ -136,6 +136,8 @@ The default browser context is accessible via [`method: Browser.contexts`]. Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers. ::: +**Usage** + ```js const browser = await playwright.chromium.connectOverCDP('http://localhost:9222'); const defaultContext = browser.contexts()[0]; @@ -218,6 +220,8 @@ A path where Playwright expects to find a bundled browser executable. Returns the browser instance. +**Usage** + You can use [`option: ignoreDefaultArgs`] to filter out `--mute-audio` from default arguments: ```js @@ -324,6 +328,8 @@ use a temporary directory instead. Returns the browser app instance. You can connect to it via [`method: BrowserType.connect`], which requires the major/minor client/server version to match (1.2.3 → is compatible with 1.2.x). +**Usage** + Launches browser server that client can connect to. An example of launching a browser executable and connecting to it later: diff --git a/docs/src/api/class-electronapplication.md b/docs/src/api/class-electronapplication.md index 5b661ccb49..a672697506 100644 --- a/docs/src/api/class-electronapplication.md +++ b/docs/src/api/class-electronapplication.md @@ -118,7 +118,8 @@ Optional argument to pass to [`param: expression`]. - returns: <[Page]> Convenience method that waits for the first application window to be opened. -Typically your script will start with: + +**Usage** ```js const electronApp = await electron.launch({ @@ -140,6 +141,8 @@ Returns the main process for this Electron Application. Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the application is closed before the event is fired. Returns the event data value. +**Usage** + ```js const [window] = await Promise.all([ electronApp.waitForEvent('window'), diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md index 295acb425d..2861d04abe 100644 --- a/docs/src/api/class-elementhandle.md +++ b/docs/src/api/class-elementhandle.md @@ -127,6 +127,8 @@ Elements from child frames return the bounding box relative to the main frame, u Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element. +**Usage** + ```js const box = await elementHandle.boundingBox(); await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2); @@ -283,6 +285,8 @@ The snippet below dispatches the `click` event on the element. Regardless of the is dispatched. This is equivalent to calling [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click). +**Usage** + ```js await elementHandle.dispatchEvent('click'); ``` @@ -381,7 +385,7 @@ details. If no elements match the selector, the method throws an error. If [`param: expression`] returns a [Promise], then [`method: ElementHandle.evalOnSelector`] would wait for the promise to resolve and return its value. -Examples: +**Usage** ```js const tweetHandle = await page.$('.tweet'); @@ -441,7 +445,7 @@ matched elements as a first argument to [`param: expression`]. See If [`param: expression`] returns a [Promise], then [`method: ElementHandle.evalOnSelectorAll`] would wait for the promise to resolve and return its value. -Examples: +**Usage** ```html
@@ -733,6 +737,8 @@ Returns the array of option values that have been successfully selected. Triggers a `change` and `input` event once all the provided options have been selected. +**Usage** + ```js // single selection matching the value handle.selectOption('blue'); @@ -912,6 +918,8 @@ Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` To press a special key, like `Control` or `ArrowDown`, use [`method: ElementHandle.press`]. +**Usage** + ```js await elementHandle.type('Hello'); // Types instantly await elementHandle.type('World', {delay: 100}); // Types slower, like a user @@ -1058,6 +1066,8 @@ appear/disappear from dom, or become visible/hidden). If at the moment of callin satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the [`option: timeout`] milliseconds, the function will throw. +**Usage** + ```js await page.setContent(`
`); const div = await page.$('div'); diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md index db137da96c..43c51065a9 100644 --- a/docs/src/api/class-frame.md +++ b/docs/src/api/class-frame.md @@ -342,6 +342,8 @@ The snippet below dispatches the `click` event on the element. Regardless of the is dispatched. This is equivalent to calling [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click). +**Usage** + ```js await frame.dispatchEvent('button#submit', 'click'); ``` @@ -482,7 +484,7 @@ elements match the selector, the method throws an error. If [`param: expression`] returns a [Promise], then [`method: Frame.evalOnSelector`] would wait for the promise to resolve and return its value. -Examples: +**Usage** ```js const searchValue = await frame.$eval('#search', el => el.value); @@ -549,7 +551,7 @@ more details. If [`param: expression`] returns a [Promise], then [`method: Frame.evalOnSelectorAll`] would wait for the promise to resolve and return its value. -Examples: +**Usage** ```js const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10); @@ -596,6 +598,8 @@ If the function passed to the [`method: Frame.evaluate`] returns a non-[Serializ [`method: Frame.evaluate`] returns `undefined`. Playwright also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`. +**Usage** + ```js const result = await frame.evaluate(([x, y]) => { return Promise.resolve(x * y); @@ -704,6 +708,8 @@ The only difference between [`method: Frame.evaluate`] and [`method: Frame.evalu If the function, passed to the [`method: Frame.evaluateHandle`], returns a [Promise], then [`method: Frame.evaluateHandle`] would wait for the promise to resolve and return its value. +**Usage** + ```js const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window)); aWindowHandle; // Handle for the window object. @@ -853,6 +859,8 @@ frame. This method throws an error if the frame has been detached before `frameElement()` returns. +**Usage** + ```js const frameElement = await frame.frameElement(); const contentFrame = await frameElement.contentFrame(); @@ -888,8 +896,11 @@ Console.WriteLine(frame == contentFrame); // -> True - returns: <[FrameLocator]> When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements -in that iframe. Following snippet locates element with text "Submit" in the iframe with id `my-frame`, -like `