diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..c5c34dfe35 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,50 @@ +### Table of contents + +1. [Core concepts](./core-concepts.md) + - [Browser](./core-concepts.md#browser) + - [Browser contexts](./core-concepts.md#browser-contexts) + - [Pages and frames](./core-concepts.md#pages-and-frames) + - [Selectors](./core-concepts.md#selectors) + - [Auto-waiting](./core-concepts.md#auto-waiting) + - [Execution contexts](./core-concepts.md#execution-contexts) + - [Object & element handles](./core-concepts.md#object--element-handles) +1. [Input](./input.md) + - [Text input](./input.md#text-input) + - [Checkboxes](./input.md#checkboxes) + - [Select options](./input.md#select-options) + - [Mouse click](./input.md#mouse-click) + - [Type characters](./input.md#type-characters) + - [Keys and shortcuts](./input.md#keys-and-shortcuts) + - [Upload files](./input.md#upload-files) + - [Focus element](./input.md#focus-element) +1. Emulation + - User agent + - Viewport, color scheme + - Devices + - Locale & Timezone + - Geolocation + - Permissions +1. Network + - Navigation & load + - Waiting for navigation + - Handling downloads + - Network events + - Mocking network + - Aborting requests +1. Scraping and verification + - Screenshots + - Evaluation +1. Selector engines + - Built-in engines + - Custom engines +1. Test runners + - Jest + - Mocha + - Karma + - Jasmine + - Jasmine + - Storybooks +1. Continuous integration + - Git Hub Action + - Docker images + - Troubleshooting \ No newline at end of file diff --git a/docs/core-concepts.md b/docs/core-concepts.md index 37973e959c..3d5a083938 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -8,9 +8,18 @@ Along with a test runner Playwright can be used to automate user interactions to validate and test web applications. The Playwright API enables this through the following primitives. -## Primitives +#### Contents + - [Browser](#browser) + - [Browser contexts](#browser-contexts) + - [Pages and frames](#pages-and-frames) + - [Selectors](#selectors) + - [Auto-waiting](#auto-waiting) + - [Execution contexts](#execution-contexts) + - [Object & element handles](#object--element-handles) -### Browser +
+ +## Browser A [`Browser`](../api.md#class-browser) refers to an instance of Chromium, Firefox or WebKit. Playwright scripts generally start with launching a browser instance @@ -27,7 +36,9 @@ await browser.close(); Launching a browser instance can be expensive, and Playwright is designed to maximize what a single instance can do through multiple browser contexts. -### Browser Context +
+ +## Browser contexts A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito-alike session within a browser instance. Browser contexts are fast and cheap to create. @@ -54,7 +65,9 @@ const context = await browser.newContext({ }); ``` -### Pages and Frames +
+ +## Pages and frames A Browser context can have multiple pages. A [`Page`](../api.md#class-page) refers to a single tab or a popup window within a browser context. A page can be used to navigate @@ -79,17 +92,15 @@ const frame = page.frame('frame-name'); await frame.fill('#username-input'); ``` -### Single Page Scenarios +
-For scenarios involving just one page, it is possible to create a new page -without explicitly creating a browser context through a convenience API. This -will create a new context internally, and closing the page will close the -context as well. +## Selectors -```js -const browser = await webkit.launch(); -const page = await browser.newPage(); -``` +
+ +## Auto-waiting + +
## Execution contexts @@ -97,10 +108,6 @@ Playwright scripts run in your Node.js environment. You page scripts run in the IMAGE PLACEHOLDER -Playwright exposes APIs to execute the JavaScript code in the context of the web page and allows calling back into the Node.js environment from your web page. - -### Using the Evaluate API - The [`page.evaluate`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageevaluatepagefunction-arg) API can run a JavaScript function in the context of the web page and bring results back to the Node.js environment. Globals like `window` and `document` along with the web page runtime can be used in `evaluate`. @@ -127,3 +134,10 @@ const result = await page.evaluate(() => { Evaluation parameters are serialized and sent into your web page over the wire. You can pass primitive types, JSON-alike objects and remote object handles received from the page. + +
+ +## Object & element handles + +
+ diff --git a/docs/input.md b/docs/input.md index 64ec68d057..bbbfd17176 100644 --- a/docs/input.md +++ b/docs/input.md @@ -1,6 +1,19 @@ -# Working with input +# Input + +#### Contents +- [Text input](#text-input) +- [Checkboxes](#checkboxes) +- [Select options](#select-options) +- [Mouse click](#mouse-click) +- [Type characters](#type-characters) +- [Keys and shortcuts](#keys-and-shortcuts) +- [Upload files](#upload-files) +- [Focus element](#focus-element) + +
+ +## Text input -## Fill out the form, enter text ```js await page.fill('#name', 'Peter'); ``` @@ -21,15 +34,15 @@ await page.fill('#local', '2020-03-02T05:15'); ``` -#### API reference +#### Reference -- [`page.fill(selector, value[, options])`](./api.md#pagefillselector-value-options) — on the main frame -- [`frame.fill(selector, value[, options])`](./api.md#framefillselector-value-options) — on a specific frame -- [`elementHandle.fill(value[, options])`](./api.md#elementhandlefillvalue-options) — on a particular element +- [page.fill(selector, value[, options])](./api.md#pagefillselector-value-options) — main frame +- [frame.fill(selector, value[, options])](./api.md#framefillselector-value-options) — given frame +- [elementHandle.fill(value[, options])](./api.md#elementhandlefillvalue-options) — given element
-## Check / uncheck the checkbox +## Checkboxes ```js // @@ -41,18 +54,18 @@ await page.uncheck('#subscribe-label'); This is the easiest way to check and uncheck a checkbox. This method can be used on the `input[type=checkbox]` and on the `label` associated with that input. -#### API reference +#### Reference -- [`page.check(selector[, options])`](./api.md#pagecheckselector-options) — on the main frame -- [`page.uncheck(selector[, options])`](./api.md#pageuncheckselector-options) — on the main frame -- [`frame.check(selector[, options])`](./api.md#framecheckselector-options) — on a specific frame -- [`frame.uncheck(selector[, options])`](./api.md#frameuncheckselector-options) — on a specific frame -- [`elementHandle.check(value[, options])`](./api.md#elementhandleuncheckoptions) — on a particular element -- [`elementHandle.uncheck(value[, options])`](./api.md#elementhandleuncheckoptions) — on a particular element +- [page.check(selector[, options])](./api.md#pagecheckselector-options) — main frame +- [page.uncheck(selector[, options])](./api.md#pageuncheckselector-options) — main frame +- [frame.check(selector[, options])](./api.md#framecheckselector-options) — given frame +- [frame.uncheck(selector[, options])](./api.md#frameuncheckselector-options) — given frame +- [elementHandle.check(value[, options])](./api.md#elementhandleuncheckoptions) — given element +- [elementHandle.uncheck(value[, options])](./api.md#elementhandleuncheckoptions) — given element
-## Select an option +## Select options ```js // + await page.type('#area', 'Hello World!'); ``` -Sometimes it is important to type into the focused field character by character, as if it was the user with the real keyboard. This method will emit all the necessary keyboard events, with all the `keydown`, `keyup`, `keypress` events in place. You can even specify the optional `delay` between the key presses to simulate real user behavior. +Note that most of the time, [`page.fill`](#text-input) will just work. You only need to type characters if there is special keyboard handling on the page. -#### API reference +But sometimes it is important to type into the field character by character, as if it was a user with a real keyboard. This method will emit all the necessary keyboard events, with all the `keydown`, `keyup`, `keypress` events in place. You can even specify the optional `delay` between the key presses to simulate real user behavior. -- [`page.type(selector, text[, options])`](./api.md#pagetypeselector-text-options) — on the main frame -- [`frame.type(selector, text[, options])`](./api.md#frametypeselector-text-options) — on a specific frame -- [`elementHandle.type(text[, options])`](./api.md#elementhandletypetext-options) — on a particular element -- [`keyboard.type(text[, options])`](./api.md#keyboardtypetext-options) — wherever the current focus is +#### Reference + +- [page.type(selector, text[, options])](./api.md#pagetypeselector-text-options) — main frame +- [frame.type(selector, text[, options])](./api.md#frametypeselector-text-options) — given frame +- [elementHandle.type(text[, options])](./api.md#elementhandletypetext-options) — given element +- [keyboard.type(text[, options])](./api.md#keyboardtypetext-options) — focused element
-## Press a key, enter keyboard shortcut +## Keys and shortcuts ```js // @@ -159,9 +224,65 @@ Shortcuts such as `"Control+o"` or `"Control+Shift+T"` are supported as well. Wh Note that you still need to specify the capital `A` in `Shift-A` to produce the capital character. `Shift-a` produces a lower-case one as if you had the `CapsLock` toggled. -#### API reference +#### Reference -- [`page.press(selector, key[, options])`](./api.md#pagepressselector-key-options) — on the main frame -- [`frame.press(selector, key[, options])`](./api.md#framepressselector-key-options) — on a specific frame -- [`elementHandle.press(key[, options])`](./api.md#elementhandlepresskey-options) — on a particular element -- [`keyboard.press(key[, options])`](./api.md#keyboardpresskey-options) — wherever the current focus is +- [page.press(selector, key[, options])](./api.md#pagepressselector-key-options) — main frame +- [frame.press(selector, key[, options])](./api.md#framepressselector-key-options) — given frame +- [elementHandle.press(key[, options])](./api.md#elementhandlepresskey-options) — given element +- [keyboard.press(key[, options])](./api.md#keyboardpresskey-options) — focused element + +
+ +## Upload files + +```js +// + +await page.setInputFiles('input#upload', 'myfile.pdf'); +``` + +You can select input files for upload using the `page.setInputFiles` method. It expects first argument to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) with the type `"file"`. Multiple files can be passed in the array. If some of the file paths are relative, they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). Empty array clears the selected files. + +#### Variations + +```js +// Select multiple files. +await page.setInputFiles('input#upload', ['file1.txt', 'file2.txt']); + +// Upload buffer from memory, without reading from file. +await page.setInputFiles('input#upload', { + name: 'file.txt', + mimeType: 'text/plain', + buffer: Buffer.from('this is test') +}); + +// Remove all the selected files +await page.setInputFiles('input#upload', []); +``` + +#### Reference + +- [page.setInputFiles(selector, files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagesetinputfilesselector-value-options) +- [frame.setInputFiles(selector, files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#framesetinputfilesselector-value-options) +- [elementHandle.setInputFiles(files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#elementhandlesetinputfilesfiles-options) + +
+ +## Focus element + + +```js +// + +await page.focus('input#name'); +``` + +For the dynamic pages that handle focus events, you can focus the given element. + +#### Reference + +- [page.focus(selector, [options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagefocusselector-options) +- [frame.focus(selector, [options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#framefocusselector-options) +- [elementHandle.focus([options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#elementhandlefocus-options) + +