Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs(input): include clicks and files sections (#1868)

Browse source
This commit is contained in:
Pavel Feldman 2020-04-19 18:47:36 -07:00 committed by GitHub
parent 92b6bc0eb9
commit 92a4c70331
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 239 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
docs/README.md Normal file
View file

@ -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

48
docs/core-concepts.md
View file

@ -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 validate and test web applications. The Playwright API enables this through
the following primitives. 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 <br/>
## Browser
A [`Browser`](../api.md#class-browser) refers to an instance of Chromium, Firefox A [`Browser`](../api.md#class-browser) refers to an instance of Chromium, Firefox
or WebKit. Playwright scripts generally start with launching a browser instance 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 Launching a browser instance can be expensive, and Playwright is designed to
maximize what a single instance can do through multiple browser contexts. maximize what a single instance can do through multiple browser contexts.
### Browser Context <br/>
## Browser contexts
A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito-alike A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito-alike
session within a browser instance. Browser contexts are fast and cheap to create. 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 <br/>
## Pages and frames
A Browser context can have multiple pages. A [`Page`](../api.md#class-page) 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 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'); await frame.fill('#username-input');
``` ```
### Single Page Scenarios <br/>
For scenarios involving just one page, it is possible to create a new page ## Selectors
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.
```js <br/>
const browser = await webkit.launch();
const page = await browser.newPage(); ## Auto-waiting
```
<br/>
## Execution contexts ## Execution contexts
@ -97,10 +108,6 @@ Playwright scripts run in your Node.js environment. You page scripts run in the
IMAGE PLACEHOLDER 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 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 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`. `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. 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. You can pass primitive types, JSON-alike objects and remote object handles received from the page.
<br/>
## Object & element handles
<br/>

195
docs/input.md
View file

@ -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)
<br/>
## Text input
## Fill out the form, enter text
```js ```js
await page.fill('#name', 'Peter'); 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 - [page.fill(selector, value[, options])](./api.md#pagefillselector-value-options) — main frame
- [`frame.fill(selector, value[, options])`](./api.md#framefillselector-value-options) — on a specific frame - [frame.fill(selector, value[, options])](./api.md#framefillselector-value-options) — given frame
- [`elementHandle.fill(value[, options])`](./api.md#elementhandlefillvalue-options) — on a particular element - [elementHandle.fill(value[, options])](./api.md#elementhandlefillvalue-options) — given element
<br/> <br/>
## Check / uncheck the checkbox ## Checkboxes
```js ```js
// <input id=agree type=checkbox></input> // <input id=agree type=checkbox></input>
@ -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. 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.check(selector[, options])](./api.md#pagecheckselector-options) — main frame
- [`page.uncheck(selector[, options])`](./api.md#pageuncheckselector-options) — on the main frame - [page.uncheck(selector[, options])](./api.md#pageuncheckselector-options) — main frame
- [`frame.check(selector[, options])`](./api.md#framecheckselector-options) — on a specific frame - [frame.check(selector[, options])](./api.md#framecheckselector-options) — given frame
- [`frame.uncheck(selector[, options])`](./api.md#frameuncheckselector-options) — on a specific frame - [frame.uncheck(selector[, options])](./api.md#frameuncheckselector-options) — given frame
- [`elementHandle.check(value[, options])`](./api.md#elementhandleuncheckoptions) — on a particular element - [elementHandle.check(value[, options])](./api.md#elementhandleuncheckoptions) — given element
- [`elementHandle.uncheck(value[, options])`](./api.md#elementhandleuncheckoptions) — on a particular element - [elementHandle.uncheck(value[, options])](./api.md#elementhandleuncheckoptions) — given element
<br/> <br/>
## Select an option ## Select options
```js ```js
// <select id=colors> // <select id=colors>
@ -71,46 +84,98 @@ You can specify option `value`, `label` or `elementHandle` to select. Multiple o
```js ```js
// Single selection matching the value // Single selection matching the value
page.selectOption('select#colors', 'blue'); await page.selectOption('select#colors', 'blue');
// Single selection matching the label // Single selection matching the label
page.selectOption('select#colors', { label: 'Blue' }); await page.selectOption('select#colors', { label: 'Blue' });
// Multiple selected items // Multiple selected items
page.selectOption('select#colors', ['red', 'green', 'blue']); await page.selectOption('select#colors', ['red', 'green', 'blue']);
// Select the option element handle // Select the option element handle
const option = await page.$('#best-option"); const option = await page.$('#best-option');
page.selectOption('select#colors', option); await page.selectOption('select#colors', option);
``` ```
#### API reference #### Reference
- [`page.selectOption(selector, values[, options])`](./api.md#pageselectoptionselector-values-options) — on the main frame - [page.selectOption(selector, values[, options])](./api.md#pageselectoptionselector-values-options) — main frame
- [`frame.selectOption(selector, values[, options])`](./api.md#frameselectoptionselector-values-options) — on a specific frame - [frame.selectOption(selector, values[, options])](./api.md#frameselectoptionselector-values-options) — given frame
- [`elementHandle.selectOption(values[, options])`](./api.md#elementhandleselectoptionvalues-options) — on a particular element - [elementHandle.selectOption(values[, options])](./api.md#elementhandleselectoptionvalues-options) — given element
<br/> <br/>
## Type character by character ## Mouse click
```js
// <button id=submit></button>
await page.click('button#submit');
```
Performs a simple human click. Under the hood, this and other pointer-related methods:
- wait for element with given selector to be in DOM
- wait for it to become displayed, i.e. not `display:none`,
- wait for it to stop moving, for example, until css transition finishes
- scroll the element into view
- wait for it to receive pointer events at the action point, for example, waits until element becomes non-obscured by other elements
#### Variations
```js
// Double click element
await page.dblclick('#item');
// Right click element
await page.click('#item', { button: 'right' });
// Shift click element
await page.click('#item', { modifiers: 'Shift' });
// Hover over element without clicking
await page.hover('#item');
// Click the top left corner of the element
await page.click('#item', { position: { x: 0, y: 0} });
```
#### Reference
- [page.click(selector[, options])](./api.md#pageclickselector-options) — main frame
- [frame.click(selector[, options])](./api.md#frameclickselector-options) — given frame
- [elementHandle.click([options])](./api.md#elementhandleclickoptions) — given element
- [page.dblclick(selector[, options])](./api.md#pagedblclickselector-options) — main frame
- [frame.dblclick(selector[, options])](./api.md#framedblclickselector-options) — given frame
- [elementHandle.dblclick([options])](./api.md#elementhandledblclickoptions) — given element
- [page.hover(selector[, options])](./api.md#pagehoverselector-options) — main frame
- [frame.hover(selector[, options])](./api.md#framehoverselector-options) — given frame
- [elementHandle.hover([options])](./api.md#elementhandlehoveroptions) — given element
<br/>
## Type characters
```js ```js
// <textarea id=area></textarea> // <textarea id=area></textarea>
await page.type('#area', 'Hello World!'); 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 #### Reference
- [`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 - [page.type(selector, text[, options])](./api.md#pagetypeselector-text-options) — main frame
- [`keyboard.type(text[, options])`](./api.md#keyboardtypetext-options) — wherever the current focus is - [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
<br/> <br/>
## Press a key, enter keyboard shortcut ## Keys and shortcuts
```js ```js
// <button id=submit></button> // <button id=submit></button>
@ -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. 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 - [page.press(selector, key[, options])](./api.md#pagepressselector-key-options) — main frame
- [`frame.press(selector, key[, options])`](./api.md#framepressselector-key-options) — on a specific frame - [frame.press(selector, key[, options])](./api.md#framepressselector-key-options) — given frame
- [`elementHandle.press(key[, options])`](./api.md#elementhandlepresskey-options) — on a particular element - [elementHandle.press(key[, options])](./api.md#elementhandlepresskey-options) — given element
- [`keyboard.press(key[, options])`](./api.md#keyboardpresskey-options) — wherever the current focus is - [keyboard.press(key[, options])](./api.md#keyboardpresskey-options) — focused element
<br/>
## Upload files
```js
// <input id=upload type=file>
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)
<br/>
## Focus element
```js
// <input id=name>
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)
<br/>