Skip to content

Commit 92a4c70

Browse files
pavelfeldmanpavelfeldman
authored
docs(input): include clicks and files sections (#1868)
1 parent 92b6bc0 commit 92a4c70

File tree

3 files changed

+239
-54
lines changed

3 files changed

+239
-54
lines changed

‎docs/README.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
### Table of contents
2+
3+
1. [Core concepts](./core-concepts.md)
4+
- [Browser](./core-concepts.md#browser)
5+
- [Browser contexts](./core-concepts.md#browser-contexts)
6+
- [Pages and frames](./core-concepts.md#pages-and-frames)
7+
- [Selectors](./core-concepts.md#selectors)
8+
- [Auto-waiting](./core-concepts.md#auto-waiting)
9+
- [Execution contexts](./core-concepts.md#execution-contexts)
10+
- [Object & element handles](./core-concepts.md#object--element-handles)
11+
1. [Input](./input.md)
12+
- [Text input](./input.md#text-input)
13+
- [Checkboxes](./input.md#checkboxes)
14+
- [Select options](./input.md#select-options)
15+
- [Mouse click](./input.md#mouse-click)
16+
- [Type characters](./input.md#type-characters)
17+
- [Keys and shortcuts](./input.md#keys-and-shortcuts)
18+
- [Upload files](./input.md#upload-files)
19+
- [Focus element](./input.md#focus-element)
20+
1. Emulation
21+
- User agent
22+
- Viewport, color scheme
23+
- Devices
24+
- Locale & Timezone
25+
- Geolocation
26+
- Permissions
27+
1. Network
28+
- Navigation & load
29+
- Waiting for navigation
30+
- Handling downloads
31+
- Network events
32+
- Mocking network
33+
- Aborting requests
34+
1. Scraping and verification
35+
- Screenshots
36+
- Evaluation
37+
1. Selector engines
38+
- Built-in engines
39+
- Custom engines
40+
1. Test runners
41+
- Jest
42+
- Mocha
43+
- Karma
44+
- Jasmine
45+
- Jasmine
46+
- Storybooks
47+
1. Continuous integration
48+
- Git Hub Action
49+
- Docker images
50+
- Troubleshooting

‎docs/core-concepts.md

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,18 @@ Along with a test runner Playwright can be used to automate user interactions to
88
validate and test web applications. The Playwright API enables this through
99
the following primitives.
1010

11-
## Primitives
11+
#### Contents
12+
- [Browser](#browser)
13+
- [Browser contexts](#browser-contexts)
14+
- [Pages and frames](#pages-and-frames)
15+
- [Selectors](#selectors)
16+
- [Auto-waiting](#auto-waiting)
17+
- [Execution contexts](#execution-contexts)
18+
- [Object & element handles](#object--element-handles)
1219

13-
### Browser
20+
<br/>
21+
22+
## Browser
1423

1524
A [`Browser`](../api.md#class-browser) refers to an instance of Chromium, Firefox
1625
or WebKit. Playwright scripts generally start with launching a browser instance
@@ -27,7 +36,9 @@ await browser.close();
2736
Launching a browser instance can be expensive, and Playwright is designed to
2837
maximize what a single instance can do through multiple browser contexts.
2938

30-
### Browser Context
39+
<br/>
40+
41+
## Browser contexts
3142

3243
A [`BrowserContext`](../api.md#class-browsercontext) is an isolated incognito-alike
3344
session within a browser instance. Browser contexts are fast and cheap to create.
@@ -54,7 +65,9 @@ const context = await browser.newContext({
5465
});
5566
```
5667

57-
### Pages and Frames
68+
<br/>
69+
70+
## Pages and frames
5871

5972
A Browser context can have multiple pages. A [`Page`](../api.md#class-page)
6073
refers to a single tab or a popup window within a browser context. A page can be used to navigate
@@ -79,28 +92,22 @@ const frame = page.frame('frame-name');
7992
await frame.fill('#username-input');
8093
```
8194

82-
### Single Page Scenarios
95+
<br/>
8396

84-
For scenarios involving just one page, it is possible to create a new page
85-
without explicitly creating a browser context through a convenience API. This
86-
will create a new context internally, and closing the page will close the
87-
context as well.
97+
## Selectors
8898

89-
```js
90-
const browser = await webkit.launch();
91-
const page = await browser.newPage();
92-
```
99+
<br/>
100+
101+
## Auto-waiting
102+
103+
<br/>
93104

94105
## Execution contexts
95106

96107
Playwright scripts run in your Node.js environment. You page scripts run in the page environment. Those environments don't intersect, they are running in different virtual machines in different processes and potentially on different computers.
97108

98109
IMAGE PLACEHOLDER
99110

100-
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.
101-
102-
### Using the Evaluate API
103-
104111
The [`page.evaluate`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageevaluatepagefunction-arg) API can run a JavaScript function in the context
105112
of the web page and bring results back to the Node.js environment. Globals like
106113
`window` and `document` along with the web page runtime can be used in `evaluate`.
@@ -127,3 +134,10 @@ const result = await page.evaluate(() => {
127134

128135
Evaluation parameters are serialized and sent into your web page over the wire.
129136
You can pass primitive types, JSON-alike objects and remote object handles received from the page.
137+
138+
<br/>
139+
140+
## Object & element handles
141+
142+
<br/>
143+

‎docs/input.md

Lines changed: 158 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,19 @@
1-
# Working with input
1+
# Input
2+
3+
#### Contents
4+
- [Text input](#text-input)
5+
- [Checkboxes](#checkboxes)
6+
- [Select options](#select-options)
7+
- [Mouse click](#mouse-click)
8+
- [Type characters](#type-characters)
9+
- [Keys and shortcuts](#keys-and-shortcuts)
10+
- [Upload files](#upload-files)
11+
- [Focus element](#focus-element)
12+
13+
<br/>
14+
15+
## Text input
216

3-
## Fill out the form, enter text
417
```js
518
await page.fill('#name', 'Peter');
619
```
@@ -21,15 +34,15 @@ await page.fill('#local', '2020-03-02T05:15');
2134

2235
```
2336

24-
#### API reference
37+
#### Reference
2538

26-
- [`page.fill(selector, value[, options])`](./api.md#pagefillselector-value-options) — on the main frame
27-
- [`frame.fill(selector, value[, options])`](./api.md#framefillselector-value-options) — on a specific frame
28-
- [`elementHandle.fill(value[, options])`](./api.md#elementhandlefillvalue-options) — on a particular element
39+
- [page.fill(selector, value[, options])](./api.md#pagefillselector-value-options) — main frame
40+
- [frame.fill(selector, value[, options])](./api.md#framefillselector-value-options) — given frame
41+
- [elementHandle.fill(value[, options])](./api.md#elementhandlefillvalue-options) — given element
2942

3043
<br/>
3144

32-
## Check / uncheck the checkbox
45+
## Checkboxes
3346

3447
```js
3548
// <input id=agree type=checkbox></input>
@@ -41,18 +54,18 @@ await page.uncheck('#subscribe-label');
4154

4255
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.
4356

44-
#### API reference
57+
#### Reference
4558

46-
- [`page.check(selector[, options])`](./api.md#pagecheckselector-options) — on the main frame
47-
- [`page.uncheck(selector[, options])`](./api.md#pageuncheckselector-options) — on the main frame
48-
- [`frame.check(selector[, options])`](./api.md#framecheckselector-options) — on a specific frame
49-
- [`frame.uncheck(selector[, options])`](./api.md#frameuncheckselector-options) — on a specific frame
50-
- [`elementHandle.check(value[, options])`](./api.md#elementhandleuncheckoptions) — on a particular element
51-
- [`elementHandle.uncheck(value[, options])`](./api.md#elementhandleuncheckoptions) — on a particular element
59+
- [page.check(selector[, options])](./api.md#pagecheckselector-options) — main frame
60+
- [page.uncheck(selector[, options])](./api.md#pageuncheckselector-options) — main frame
61+
- [frame.check(selector[, options])](./api.md#framecheckselector-options) — given frame
62+
- [frame.uncheck(selector[, options])](./api.md#frameuncheckselector-options) — given frame
63+
- [elementHandle.check(value[, options])](./api.md#elementhandleuncheckoptions) — given element
64+
- [elementHandle.uncheck(value[, options])](./api.md#elementhandleuncheckoptions) — given element
5265

5366
<br/>
5467

55-
## Select an option
68+
## Select options
5669

5770
```js
5871
// <select id=colors>
@@ -71,46 +84,98 @@ You can specify option `value`, `label` or `elementHandle` to select. Multiple o
7184

7285
```js
7386
// Single selection matching the value
74-
page.selectOption('select#colors', 'blue');
87+
await page.selectOption('select#colors', 'blue');
7588

7689
// Single selection matching the label
77-
page.selectOption('select#colors', { label: 'Blue' });
90+
await page.selectOption('select#colors', { label: 'Blue' });
7891

7992
// Multiple selected items
80-
page.selectOption('select#colors', ['red', 'green', 'blue']);
93+
await page.selectOption('select#colors', ['red', 'green', 'blue']);
8194

8295
// Select the option element handle
83-
const option = await page.$('#best-option");
84-
page.selectOption('select#colors', option);
96+
const option = await page.$('#best-option');
97+
await page.selectOption('select#colors', option);
8598
```
8699

87-
#### API reference
100+
#### Reference
88101

89-
- [`page.selectOption(selector, values[, options])`](./api.md#pageselectoptionselector-values-options) — on the main frame
90-
- [`frame.selectOption(selector, values[, options])`](./api.md#frameselectoptionselector-values-options) — on a specific frame
91-
- [`elementHandle.selectOption(values[, options])`](./api.md#elementhandleselectoptionvalues-options) — on a particular element
102+
- [page.selectOption(selector, values[, options])](./api.md#pageselectoptionselector-values-options) — main frame
103+
- [frame.selectOption(selector, values[, options])](./api.md#frameselectoptionselector-values-options) — given frame
104+
- [elementHandle.selectOption(values[, options])](./api.md#elementhandleselectoptionvalues-options) — given element
92105

93106
<br/>
94107

95-
## Type character by character
108+
## Mouse click
109+
110+
```js
111+
// <button id=submit></button>
112+
113+
await page.click('button#submit');
114+
```
115+
116+
Performs a simple human click. Under the hood, this and other pointer-related methods:
117+
118+
- wait for element with given selector to be in DOM
119+
- wait for it to become displayed, i.e. not `display:none`,
120+
- wait for it to stop moving, for example, until css transition finishes
121+
- scroll the element into view
122+
- wait for it to receive pointer events at the action point, for example, waits until element becomes non-obscured by other elements
123+
124+
#### Variations
125+
126+
```js
127+
// Double click element
128+
await page.dblclick('#item');
129+
130+
// Right click element
131+
await page.click('#item', { button: 'right' });
132+
133+
// Shift click element
134+
await page.click('#item', { modifiers: 'Shift' });
135+
136+
// Hover over element without clicking
137+
await page.hover('#item');
138+
139+
// Click the top left corner of the element
140+
await page.click('#item', { position: { x: 0, y: 0} });
141+
```
142+
143+
#### Reference
144+
145+
- [page.click(selector[, options])](./api.md#pageclickselector-options) — main frame
146+
- [frame.click(selector[, options])](./api.md#frameclickselector-options) — given frame
147+
- [elementHandle.click([options])](./api.md#elementhandleclickoptions) — given element
148+
- [page.dblclick(selector[, options])](./api.md#pagedblclickselector-options) — main frame
149+
- [frame.dblclick(selector[, options])](./api.md#framedblclickselector-options) — given frame
150+
- [elementHandle.dblclick([options])](./api.md#elementhandledblclickoptions) — given element
151+
- [page.hover(selector[, options])](./api.md#pagehoverselector-options) — main frame
152+
- [frame.hover(selector[, options])](./api.md#framehoverselector-options) — given frame
153+
- [elementHandle.hover([options])](./api.md#elementhandlehoveroptions) — given element
154+
155+
<br/>
156+
157+
## Type characters
96158

97159
```js
98160
// <textarea id=area></textarea>
161+
99162
await page.type('#area', 'Hello World!');
100163
```
101164

102-
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.
165+
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.
166+
167+
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.
103168

104-
#### API reference
169+
#### Reference
105170

106-
- [`page.type(selector, text[, options])`](./api.md#pagetypeselector-text-options) — on the main frame
107-
- [`frame.type(selector, text[, options])`](./api.md#frametypeselector-text-options) — on a specific frame
108-
- [`elementHandle.type(text[, options])`](./api.md#elementhandletypetext-options) — on a particular element
109-
- [`keyboard.type(text[, options])`](./api.md#keyboardtypetext-options) — wherever the current focus is
171+
- [page.type(selector, text[, options])](./api.md#pagetypeselector-text-options) — main frame
172+
- [frame.type(selector, text[, options])](./api.md#frametypeselector-text-options) — given frame
173+
- [elementHandle.type(text[, options])](./api.md#elementhandletypetext-options) — given element
174+
- [keyboard.type(text[, options])](./api.md#keyboardtypetext-options) — focused element
110175

111176
<br/>
112177

113-
## Press a key, enter keyboard shortcut
178+
## Keys and shortcuts
114179

115180
```js
116181
// <button id=submit></button>
@@ -159,9 +224,65 @@ Shortcuts such as `"Control+o"` or `"Control+Shift+T"` are supported as well. Wh
159224
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.
160225

161226

162-
#### API reference
227+
#### Reference
228+
229+
- [page.press(selector, key[, options])](./api.md#pagepressselector-key-options) — main frame
230+
- [frame.press(selector, key[, options])](./api.md#framepressselector-key-options) — given frame
231+
- [elementHandle.press(key[, options])](./api.md#elementhandlepresskey-options) — given element
232+
- [keyboard.press(key[, options])](./api.md#keyboardpresskey-options) — focused element
163233

164-
- [`page.press(selector, key[, options])`](./api.md#pagepressselector-key-options) — on the main frame
165-
- [`frame.press(selector, key[, options])`](./api.md#framepressselector-key-options) — on a specific frame
166-
- [`elementHandle.press(key[, options])`](./api.md#elementhandlepresskey-options) — on a particular element
167-
- [`keyboard.press(key[, options])`](./api.md#keyboardpresskey-options) — wherever the current focus is
234+
<br/>
235+
236+
## Upload files
237+
238+
```js
239+
// <input id=upload type=file>
240+
241+
await page.setInputFiles('input#upload', 'myfile.pdf');
242+
```
243+
244+
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.
245+
246+
#### Variations
247+
248+
```js
249+
// Select multiple files.
250+
await page.setInputFiles('input#upload', ['file1.txt', 'file2.txt']);
251+
252+
// Upload buffer from memory, without reading from file.
253+
await page.setInputFiles('input#upload', {
254+
name: 'file.txt',
255+
mimeType: 'text/plain',
256+
buffer: Buffer.from('this is test')
257+
});
258+
259+
// Remove all the selected files
260+
await page.setInputFiles('input#upload', []);
261+
```
262+
263+
#### Reference
264+
265+
- [page.setInputFiles(selector, files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagesetinputfilesselector-value-options)
266+
- [frame.setInputFiles(selector, files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#framesetinputfilesselector-value-options)
267+
- [elementHandle.setInputFiles(files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#elementhandlesetinputfilesfiles-options)
268+
269+
<br/>
270+
271+
## Focus element
272+
273+
274+
```js
275+
// <input id=name>
276+
277+
await page.focus('input#name');
278+
```
279+
280+
For the dynamic pages that handle focus events, you can focus the given element.
281+
282+
#### Reference
283+
284+
- [page.focus(selector, [options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagefocusselector-options)
285+
- [frame.focus(selector, [options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#framefocusselector-options)
286+
- [elementHandle.focus([options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#elementhandlefocus-options)
287+
288+
<br/>

0 commit comments

Comments
 (0)