diff --git a/docs/examples/README.md b/docs/examples/README.md index 051a6cff30..5de03ae3ae 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -1,6 +1,6 @@ # Get started with examples -Learn how to install Playwright, set up your dev environment to author Playwright scripts, and example recipes to bootstrap your scripts. +Learn how to install Playwright, set up your dev environment, and read through example recipes. Use the [API reference](../api.md) for more exhaustive documentation. ## Installing Playwright @@ -25,17 +25,18 @@ const { chromium } = require('playwright'); Playwright scripts can be developed just like any other Node.js script. For example, you can use the [Node.js debugger](https://nodejs.org/api/debugger.html) or [VS Code debugging](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) to set breakpoints and get fine grained control over execution. -### Running browsers for debugging +#### Running browsers for debugging + +Chromium Developer Tools By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless: false` flag while launching the browser. You can also use `slowMo` to slow down execution. ```js - chromium.launch({ headless: false, slowMo: 50 }); +chromium.launch({ headless: false, slowMo: 50 }); ``` It is also possible to open **browser developer tools** during execution, to inspect the DOM tree or network activity. This is possible in Chromium, Firefox and WebKit. -

Chromium Developer Tools

## Core concepts @@ -43,6 +44,35 @@ It is also possible to open **browser developer tools** during execution, to ins * A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito session within a browser instance. Browser contexts are fast to create and can be used to parallelize isolated test executions. * A [`Page`](../api.md#class-page) refers to a single tab within a browser context, which includes one or more [`Frame`](../api.md#class-frame) objects. +#### Working with elements + +* Selector engines: Playwright can query elements on a web page through [multiple selector engines](../selectors.md) like CSS, HTML attributes, XPath and text contents. +* Actions on elements: Use methods like [`page.click`](../api.md#pageclickselector-options) or [`page.fill`](../api.md#pagefillselector-value-options) to execute actions on elements. + * **Auto-wait** for elements: These actions auto-wait for the element to be ready. If these actions result in page navigations, they are also awaited automatically. + + ```js + // Wait for element to be ready, click it and wait for navigations (if any) + await page.click('text="Login"'); + ``` + +* Use the [`page.waitForSelector`](../api.md#pagewaitforselectorselector-options) method to explicitly wait for elements. + + ```js + // Explicitly wait for the #search field to be present in the DOM + const search = await page.waitForSelector('#search'); + // Retrieve the query value from the element + const query = await search.evaluate(element => element.value); + ``` + +* Assertions on elements: Use [`page.$`](../api.md#pageselector) to get the element from the page and [`page.$eval`](../api.md#pageevalselector-pagefunction-arg-1) to run a JS function in the execution context of the page. + * These can be used to assert element properties, like visibility or text contents. + * These methods behave similar to the `$` operator in DevTools console or jQuery. They fetch the element from the page without waiting. If required, use `page.waitForSelector` and `evaluate` instead, as described above. + + ```js + // Get value of the #search field + const query = await page.$eval('#search', element => element.value); + ``` + ## Example recipes ### [Authentication](authentication.js) @@ -60,4 +90,4 @@ Other examples * Handling a popup, eg, accept dialog * Page navigation and wait for load * Async page load (see #662) ---> \ No newline at end of file +--> diff --git a/docs/showcase.md b/docs/showcase.md index af86621fb9..956aa225b0 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -36,6 +36,7 @@ * [react-app-playwright](https://github.com/KyleADay/react-app-playwright): Using Playwright with a create-react-app project * [playwright-react-typescript-jest-example](https://github.com/azemetre/playwright-react-typescript-jest-example): Using Playwright + Jest with a custom webpack configuration for React + Typescript project * [playwright-mocha](https://github.com/roggerfe/playwright-mocha): Using Playwright with Mocha and Chai +* [playwright-cljs](https://github.com/apeckham/playwright-cljs): Playwright examples in ClojureScript * [playwright-github-actions](https://github.com/arjun27/playwright-github-actions/actions): Playwright setup on GitHub Actions * [playwright-azure-functions](https://github.com/arjun27/playwright-azure-functions): Playwright setup on Azure Functions * [playwright-aws-lambda](https://github.com/austinkelleher/playwright-aws-lambda): Playwright setup on AWS Lambda