Skip to content

Commit

Permalink
api(chromium): remove Target from public API (#1163)
Browse files Browse the repository at this point in the history
  • Loading branch information
@yury-s
yury-s authored Mar 2, 2020
1 parent f242e0c commit a57978a
Show file tree
Hide file tree
Showing 13 changed files with 194 additions and 321 deletions.
155 changes: 47 additions & 108 deletions docs/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
- [class: Browser](#class-browser)
- [class: BrowserContext](#class-browsercontext)
- [class: Page](#class-page)
- [class: PageEvent](#class-pageevent)
- [class: Frame](#class-frame)
- [class: ElementHandle](#class-elementhandle)
- [class: JSHandle](#class-jshandle)
Expand All @@ -28,7 +29,6 @@
- [class: ChromiumBrowserContext](#class-chromiumbrowsercontext)
- [class: ChromiumCoverage](#class-chromiumcoverage)
- [class: ChromiumSession](#class-chromiumsession)
- [class: ChromiumTarget](#class-chromiumtarget)
- [class: FirefoxBrowser](#class-firefoxbrowser)
- [class: WebKitBrowser](#class-webkitbrowser)
- [Environment Variables](#environment-variables)
Expand Down Expand Up @@ -265,6 +265,7 @@ await context.close();

<!-- GEN:toc -->
- [event: 'close'](#event-close)
- [event: 'page'](#event-page)
- [browserContext.addInitScript(script[, ...args])](#browsercontextaddinitscriptscript-args)
- [browserContext.clearCookies()](#browsercontextclearcookies)
- [browserContext.clearPermissions()](#browsercontextclearpermissions)
Expand All @@ -287,6 +288,12 @@ Emitted when Browser context gets closed. This might happen because of one of th
- Browser application is closed or crashed.
- The [`browser.close`](#browserclose) method was called.

#### event: 'page'
- <[PageEvent]>

Emitted when a new Page is created in the BrowserContext. The event will also fire for popup
pages.

#### browserContext.addInitScript(script[, ...args])
- `script` <[function]|[string]|[Object]> Script to be evaluated in all pages in the browser context.
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
Expand All @@ -312,7 +319,6 @@ await browserContext.addInitScript(preloadFile);
```

> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript(script[, ...args])](#browsercontextaddinitscriptscript-args) and [page.addInitScript(script[, ...args])](#pageaddinitscriptscript-args) is not defined.
#### browserContext.clearCookies()
- returns: <[Promise]>

Expand Down Expand Up @@ -361,7 +367,8 @@ If URLs are specified, only cookies that affect those URLs are returned.
Creates a new page in the browser context.

#### browserContext.pages()
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [chromiumTarget.page()](#chromiumtargetpage).
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using
[chromiumBrowserContext.backgroundPages()](#chromiumbrowsercontextbackgroundpages).

An array of all pages inside the browser context.

Expand Down Expand Up @@ -1662,6 +1669,13 @@ This method returns all of the dedicated [WebWorkers](https://developer.mozilla.

> **NOTE** This does not contain ServiceWorkers
### class: PageEvent

Event object passed to the listeners of ['page'](#event-page) on [`BrowserContext`](#class-browsercontext). Provides access
to the newly created page.

#### pageEvent.page()
- returns: <[Promise]<[Page]>> Promise which resolves to the created page.

### class: Frame

Expand Down Expand Up @@ -3556,7 +3570,7 @@ await browser.stopTracing();
```

<!-- GEN:toc -->
- [chromiumBrowser.browserTarget()](#chromiumbrowserbrowsertarget)
- [chromiumBrowser.createBrowserSession()](#chromiumbrowsercreatebrowsersession)
- [chromiumBrowser.startTracing(page, [options])](#chromiumbrowserstarttracingpage-options)
- [chromiumBrowser.stopTracing()](#chromiumbrowserstoptracing)
<!-- GEN:stop -->
Expand All @@ -3569,10 +3583,9 @@ await browser.stopTracing();
- [browser.newPage([options])](#browsernewpageoptions)
<!-- GEN:stop -->

#### chromiumBrowser.browserTarget()
- returns: <[ChromiumTarget]>

Returns browser target.
#### chromiumBrowser.createBrowserSession()
- returns: <[Promise]<[ChromiumSession]>> Promise that resolves to the newly created browser
session.

#### chromiumBrowser.startTracing(page, [options])
- `page` <[Page]> Optional, if specified, tracing includes screenshots of the given page.
Expand All @@ -3599,15 +3612,14 @@ const backgroundPage = await backroundPageTarget.page();
```

<!-- GEN:toc -->
- [event: 'targetchanged'](#event-targetchanged)
- [event: 'targetcreated'](#event-targetcreated)
- [event: 'targetdestroyed'](#event-targetdestroyed)
- [chromiumBrowserContext.pageTarget(page)](#chromiumbrowsercontextpagetargetpage)
- [chromiumBrowserContext.targets()](#chromiumbrowsercontexttargets)
- [chromiumBrowserContext.waitForTarget(predicate[, options])](#chromiumbrowsercontextwaitfortargetpredicate-options)
- [event: 'backgroundpage'](#event-backgroundpage)
- [event: 'serviceworker'](#event-serviceworker)
- [chromiumBrowserContext.backgroundPages()](#chromiumbrowsercontextbackgroundpages)
- [chromiumBrowserContext.createSession(page)](#chromiumbrowsercontextcreatesessionpage)
<!-- GEN:stop -->
<!-- GEN:toc-extends-BrowserContext -->
- [event: 'close'](#event-close)
- [event: 'page'](#event-page)
- [browserContext.addInitScript(script[, ...args])](#browsercontextaddinitscriptscript-args)
- [browserContext.clearCookies()](#browsercontextclearcookies)
- [browserContext.clearPermissions()](#browsercontextclearpermissions)
Expand All @@ -3623,50 +3635,24 @@ const backgroundPage = await backroundPageTarget.page();
- [browserContext.setPermissions(origin, permissions[])](#browsercontextsetpermissionsorigin-permissions)
<!-- GEN:stop -->

#### event: 'targetchanged'
- <[ChromiumTarget]>

Emitted when the url of a target changes.

> **NOTE** Only includes targets from this browser context.

#### event: 'targetcreated'
- <[ChromiumTarget]>

Emitted when a target is created, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browserContext.newPage`](#browsercontextnewpage).
#### event: 'backgroundpage'
- <[PageEvent]>

> **NOTE** Only includes targets from this browser context.
Emitted when new background page is created in the context.

#### event: 'targetdestroyed'
- <[ChromiumTarget]>
> **NOTE** Only works with persistent context.
Emitted when a target is destroyed, for example when a page is closed.

> **NOTE** Only includes targets from this browser context.
#### chromiumBrowserContext.pageTarget(page)
- `page` <[Page]> Page to return target for.
- returns: <[ChromiumTarget]> a target given page was created from.

#### chromiumBrowserContext.targets()
- returns: <[Array]<[ChromiumTarget]>>

An array of all active targets inside the browser context.
#### event: 'serviceworker'
- <[Worker]>

#### chromiumBrowserContext.waitForTarget(predicate[, options])
- `predicate` <[function]\([ChromiumTarget]\):[boolean]> A function to be run for every target
- `options` <[Object]>
- `timeout` <[number]> Maximum wait time in milliseconds. Pass `0` to disable the timeout. Defaults to 30 seconds.
- returns: <[Promise]<[ChromiumTarget]>> Promise which resolves to the first target found that matches the `predicate` function.
Emitted when new service worker is created in the context.

This searches for a target in the browser context.
#### chromiumBrowserContext.backgroundPages()
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all existing background pages in the context.

An example of finding a target for a page opened via `window.open`:
```js
await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await page.context().waitForTarget(target => target.url() === 'https://www.example.com/');
```
#### chromiumBrowserContext.createSession(page)
- `page` <[Page]> Page to create new session for.
- returns: <[Promise]<[ChromiumSession]>> Promise that resolves to the newly created session.

### class: ChromiumCoverage

Expand Down Expand Up @@ -3737,7 +3723,7 @@ reported.

* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)

The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
The `ChromiumSession` instances are used to talk raw Chrome Devtools Protocol:
- protocol methods can be called with `session.send` method.
- protocol events can be subscribed to with `session.on` method.

Expand All @@ -3746,7 +3732,7 @@ Useful links:
- Getting Started with DevTools Protocol: https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md

```js
const client = await chromium.pageTarget(page).createCDPSession();
const client = await page.context().createSession(page);
await client.send('Animation.enable');
client.on('Animation.animationCreated', () => console.log('Animation created!'));
const response = await client.send('Animation.getPlaybackRate');
Expand All @@ -3764,61 +3750,14 @@ await client.send('Animation.setPlaybackRate', {
#### chromiumSession.detach()
- returns: <[Promise]>

Detaches the cdpSession from the target. Once detached, the cdpSession object won't emit any events and can't be used
Detaches the chromiumSession from the target. Once detached, the chromiumSession object won't emit any events and can't be used
to send messages.

#### chromiumSession.send(method[, params])
- `method` <[string]> protocol method name
- `params` <[Object]> Optional method parameters
- returns: <[Promise]<[Object]>>

### class: ChromiumTarget


<!-- GEN:toc -->
- [chromiumTarget.context()](#chromiumtargetcontext)
- [chromiumTarget.createCDPSession()](#chromiumtargetcreatecdpsession)
- [chromiumTarget.opener()](#chromiumtargetopener)
- [chromiumTarget.page()](#chromiumtargetpage)
- [chromiumTarget.serviceWorker()](#chromiumtargetserviceworker)
- [chromiumTarget.type()](#chromiumtargettype)
- [chromiumTarget.url()](#chromiumtargeturl)
<!-- GEN:stop -->

#### chromiumTarget.context()

- returns: <[BrowserContext]>

The browser context the target belongs to.

#### chromiumTarget.createCDPSession()
- returns: <[Promise]<[CDPSession]>>

Creates a Chrome Devtools Protocol session attached to the target.

#### chromiumTarget.opener()
- returns: <?[ChromiumTarget]>

Get the target that opened this target. Top-level targets return `null`.

#### chromiumTarget.page()
- returns: <[Promise]<?[Page]>>

If the target is not of type `"page"` or `"background_page"`, returns `null`.

#### chromiumTarget.serviceWorker()
- returns: <[Promise]<?[Worker]>>

Attaches to the service worker target. If the target is not of type `"service_worker"`, returns `null`.

#### chromiumTarget.type()
- returns: <"page"|"background_page"|"service_worker"|"shared_worker"|"other"|"browser">

Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](https://developer.chrome.com/extensions/background_pages), `"service_worker"`, `"shared_worker"`, `"browser"` or `"other"`.

#### chromiumTarget.url()
- returns: <[string]>

### class: FirefoxBrowser

* extends: [Browser]
Expand Down Expand Up @@ -3908,18 +3847,18 @@ const { chromium } = require('playwright');

(async () => {
const pathToExtension = require('path').join(__dirname, 'my-extension');
const browser = await chromium.launch({
const userDataDir = '/tmp/test-user-data-dir';
const browserContext = await chromium.launchPersistent(userDataDir,{
headless: false,
args: [
`--disable-extensions-except=${pathToExtension}`,
`--load-extension=${pathToExtension}`
]
});
const targets = await browser.targets();
const backgroundPageTarget = targets.find(target => target.type() === 'background_page');
const backgroundPage = await backgroundPageTarget.page();
const backgroundPages = await browserContext.backgroundPages();
const backgroundPage = backgroundPages[0];
// Test the background page as you would any other page.
await browser.close();
await browserContext.close();
})();
```

Expand All @@ -3939,7 +3878,6 @@ const { chromium } = require('playwright');
[ChromiumBrowser]: #class-chromiumbrowser "ChromiumBrowser"
[ChromiumBrowserContext]: #class-chromiumbrowsercontext "ChromiumBrowserContext"
[ChromiumSession]: #class-chromiumsession "ChromiumSession"
[ChromiumTarget]: #class-chromiumtarget "ChromiumTarget"
[ConsoleMessage]: #class-consolemessage "ConsoleMessage"
[Coverage]: #class-coverage "Coverage"
[Dialog]: #class-dialog "Dialog"
Expand All @@ -3956,6 +3894,7 @@ const { chromium } = require('playwright');
[Mouse]: #class-mouse "Mouse"
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
[Page]: #class-page "Page"
[PageEvent]: #class-page "PageEvent"
[Playwright]: #class-playwright "Playwright"
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
Expand Down
3 changes: 1 addition & 2 deletions src/api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,14 +25,13 @@ export { Frame } from './frames';
export { Keyboard, Mouse } from './input';
export { JSHandle } from './javascript';
export { Request, Response } from './network';
export { FileChooser, Page, Worker } from './page';
export { FileChooser, Page, PageEvent, Worker } from './page';
export { Selectors } from './selectors';

export { CRBrowser as ChromiumBrowser } from './chromium/crBrowser';
export { CRBrowserContext as ChromiumBrowserContext } from './chromium/crBrowser';
export { CRCoverage as ChromiumCoverage } from './chromium/crCoverage';
export { CRSession as ChromiumSession } from './chromium/crConnection';
export { CRTarget as ChromiumTarget } from './chromium/crTarget';

export { FFBrowser as FirefoxBrowser } from './firefox/ffBrowser';

Expand Down
Loading

0 comments on commit a57978a

Please sign in to comment.