microsoft/playwright
1
1
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2024-12-14 21:53:35 +03:00
Code Issues Projects Releases Wiki Activity

docs: link to the new docs from source (#5092)

Browse Source
This commit is contained in:
Pavel Feldman 2021-01-21 14:35:20 -08:00 committed by GitHub
parent c757ba72a9
commit 8f06761ba1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 803 additions and 891 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/src/api/class-elementhandle.md
View File

@ -62,7 +62,7 @@ ElementHandle instances can be used as an argument in [`method: Page.$eval`] and
- returns: <[null]|[ElementHandle]>
The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See
[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
[Working with selectors](./selectors.md) for more details. If no elements match the selector,
returns `null`.
### param: ElementHandle.$.selector = %%-query-selector-%%
@ -73,7 +73,7 @@ returns `null`.
- returns: <[Array]<[ElementHandle]>>
The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See
[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
[Working with selectors](./selectors.md) for more details. If no elements match the selector,
returns empty array.
### param: ElementHandle.$$.selector = %%-query-selector-%%
@ -86,7 +86,7 @@ returns empty array.
Returns the return value of [`param: pageFunction`]
The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first
argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md#working-with-selectors) for more
argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for more
details. If no elements match the selector, the method throws an error.
If [`param: pageFunction`] returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its
@ -134,7 +134,7 @@ Returns the return value of [`param: pageFunction`]
The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of
matched elements as a first argument to [`param: pageFunction`]. See
[Working with selectors](./selectors.md#working-with-selectors) for more details.
[Working with selectors](./selectors.md) for more details.
If [`param: pageFunction`] returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its
value.

24
docs/src/api/class-frame.md
View File

@ -82,7 +82,7 @@ with sync_playwright() as playwright:
Returns the ElementHandle pointing to the frame element.
The method finds an element matching the specified selector within the frame. See
[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
[Working with selectors](./selectors.md) for more details. If no elements match the selector,
returns `null`.
### param: Frame.$.selector = %%-query-selector-%%
@ -95,7 +95,7 @@ returns `null`.
Returns the ElementHandles pointing to the frame elements.
The method finds all elements matching the specified selector within the frame. See
[Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector,
[Working with selectors](./selectors.md) for more details. If no elements match the selector,
returns empty array.
### param: Frame.$$.selector = %%-query-selector-%%
@ -108,7 +108,7 @@ returns empty array.
Returns the return value of [`param: pageFunction`]
The method finds an element matching the specified selector within the frame and passes it as a first argument to
[`param: pageFunction`]. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no
[`param: pageFunction`]. See [Working with selectors](./selectors.md) for more details. If no
elements match the selector, the method throws an error.
If [`param: pageFunction`] returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its
@ -155,7 +155,7 @@ Optional argument to pass to [`param: pageFunction`]
Returns the return value of [`param: pageFunction`]
The method finds all elements matching the specified selector within the frame and passes an array of matched elements
as a first argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md#working-with-selectors) for
as a first argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for
more details.
If [`param: pageFunction`] returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its
@ -416,9 +416,9 @@ Returns the return value of [`param: pageFunction`]
If the function passed to the [`method: Frame.evaluate`] returns a [Promise], then [`method: Frame.evaluate`] would wait for the promise to
resolve and return its value.
If the function passed to the [`method: Frame.evaluate`] returns a non-[Serializable] value, then[ method: `Frame.evaluate`] returns
`undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`:
`-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
If the function passed to the [`method: Frame.evaluate`] returns a non-[Serializable] value, then
[`method: Frame.evaluate`] returns `undefined`. DevTools Protocol also supports transferring some additional values that
are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
```js
const result = await frame.evaluate(([x, y]) => {
@ -493,11 +493,11 @@ Optional argument to pass to [`param: pageFunction`]
Returns the return value of [`param: pageFunction`] as in-page object (JSHandle).
The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that[ method: Fframe.evaluateHandle`] returns in-page
object (JSHandle).
The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that
[method: Frame.evaluateHandle`] returns in-page object (JSHandle).
If the function, passed to the [`method: Frame.evaluateHandle`], returns a [Promise], then[ method: Fframe.evaluateHandle`] would wait for
the promise to resolve and return its value.
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.
```js
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
@ -1024,7 +1024,7 @@ Returns frame's url.
Returns when the [`param: pageFunction`] returns a truthy value, returns that value.
The `waitForFunction` can be used to observe viewport size change:
The [`method: Frame.waitForFunction`] can be used to observe viewport size change:
```js
const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.

12
docs/src/api/class-page.md
View File

@ -829,12 +829,12 @@ page.evaluate("matchMedia('(prefers-color-scheme: no-preference)').matches")
Returns the value of the [`param: pageFunction`] invocation.
If the function passed to the [`method: Page.evaluate`] returns a [Promise], then [`method: Page.evaluate`] would wait for the promise to
resolve and return its value.
If the function passed to the [`method: Page.evaluate`] returns a [Promise], then [`method: Page.evaluate`] would wait
for the promise to resolve and return its value.
If the function passed to the [`method: Page.evaluate`] returns a non-[Serializable] value, then[ method: `Page.evaluate`] resolves to
`undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`:
`-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
If the function passed to the [`method: Page.evaluate`] returns a non-[Serializable] value, then
[`method: Page.evaluate`] resolves to `undefined`. DevTools Protocol also supports transferring some additional values
that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
Passing argument to [`param: pageFunction`]:
@ -2206,7 +2206,7 @@ Either a predicate that receives an event or an options object. Optional.
Returns when the [`param: pageFunction`] returns a truthy value. It resolves to a JSHandle of the truthy value.
The `waitForFunction` can be used to observe viewport size change:
The [`method: Page.waitForFunction`] can be used to observe viewport size change:
```js
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.

2
docs/src/api/class-playwright.md
View File

@ -157,7 +157,7 @@ This object can be used to launch or connect to Firefox, returning instances of
- type: <[Selectors]>
Selectors can be used to install custom selector engines. See
[Working with selectors](./selectors.md#working-with-selectors) for more information.
[Working with selectors](./selectors.md) for more information.
## property: Playwright.webkit
- type: <[BrowserType]>

2
docs/src/api/class-selectors.md
View File

@ -1,7 +1,7 @@
# class: Selectors
Selectors can be used to install custom selector engines. See
[Working with selectors](./selectors.md#working-with-selectors) for more information.
[Working with selectors](./selectors.md) for more information.
## async method: Selectors.register

4
docs/src/api/params.md
View File

@ -45,7 +45,7 @@ Whether to bypass the [actionability](./actionability.md) checks. Defaults to `f
- `selector` <[string]>
A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See
[working with selectors](./selectors.md#working-with-selectors) for more details.
[working with selectors](./selectors.md) for more details.
## input-position
- `position` <[Object]>
@ -85,7 +85,7 @@ defaults to 1. See [UIEvent.detail].
## query-selector
- `selector` <[string]>
A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
A selector to query for. See [working with selectors](./selectors.md) for more details.
## wait-for-selector-state
- `state` <"attached"|"detached"|"visible"|"hidden">

1598
types/types.d.ts vendored
View File

File diff suppressed because it is too large Load Diff

44
utils/generate_types/index.js
View File

@ -39,9 +39,9 @@ let hadChanges = false;
documentation = parseApi(path.join(PROJECT_DIR, 'docs', 'src', 'api'));
documentation.filterForLanguage('js');
documentation.copyDocsFromSuperclasses([]);
const createMemberLink = (text) => {
const createMemberLink = (clazz, text) => {
const anchor = text.toLowerCase().split(',').map(c => c.replace(/[^a-z]/g, '')).join('-');
return `[${text}](https://github.com/microsoft/playwright/blob/master/docs/api.md#${anchor})`;
return `[${text}](https://playwright.dev/docs/api/class-${clazz.name.toLowerCase()}#${anchor})`;
};
documentation.setLinkRenderer(item => {
const { clazz, member, param, option } = item;
@ -52,11 +52,11 @@ let hadChanges = false;
if (clazz)
return `[${clazz.name}]`;
if (member.kind === 'method')
return createMemberLink(`${member.clazz.varName}.${member.name}(…)`);
return createMemberLink(member.clazz, `${member.clazz.varName}.${member.name}(${renderJSSignature(member.argsArray)})`);
if (member.kind === 'event')
return createMemberLink(`${member.clazz.varName}.on('${member.name}')`);
return createMemberLink(member.clazz, `${member.clazz.varName}.on('${member.name}')`);
if (member.kind === 'property')
return createMemberLink(`${member.clazz.varName}.${member.name}`);
return createMemberLink(member.clazz, `${member.clazz.varName}.${member.name}`);
throw new Error('Unknown member kind ' + member.kind);
});
documentation.generateSourceCodeComments();
@ -283,10 +283,9 @@ function writeComment(comment, indent = '') {
pushLine(line);
}
comment = out.join('\n');
comment = comment.replace(/\[`([^`]+)`\]\(#([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/api.md#$2)');
comment = comment.replace(/\[([^\]]+)\]\(#([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/api.md#$2)');
comment = comment.replace(/\[`([^`]+)`\]\(\.\/([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/$2)');
comment = comment.replace(/\[([^\]]+)\]\(\.\/([^\)]+)\)/g, '[$1](https://github.com/microsoft/playwright/blob/master/docs/$2)');
comment = comment.replace(/\[([^\]]+)\]\(\.\/([^\)]+)\)/g, (match, p1, p2) => {
return `[${p1}](https://playwright.dev/docs/${p2.replace('.md', '')})`;
});
parts.push(indent + '/**');
parts.push(...comment.split('\n').map(line => indent + ' * ' + line.replace(/\*\//g, '*\\/')));
@ -392,3 +391,30 @@ ${namedDevices}
[key: string]: DeviceDescriptor;
}`;
}
/**
* @param {Documentation.Member[]} args
*/
function renderJSSignature(args) {
const tokens = [];
let hasOptional = false;
for (const arg of args) {
const name = arg.name;
const optional = !arg.required;
if (tokens.length) {
if (optional && !hasOptional)
tokens.push(`[, ${name}`);
else
tokens.push(`, ${name}`);
} else {
if (optional && !hasOptional)
tokens.push(`[${name}`);
else
tokens.push(`${name}`);
}
hasOptional = hasOptional || optional;
}
if (hasOptional)
tokens.push(']');
return tokens.join('');
}