Skip to content

Commit

Permalink
api(review): misc changes to API. (#1356)
Browse files Browse the repository at this point in the history
  • Loading branch information
pavelfeldman authored Mar 12, 2020
1 parent 7fe5656 commit b43f33f
Show file tree
Hide file tree
Showing 11 changed files with 60 additions and 87 deletions.
85 changes: 29 additions & 56 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,15 +192,15 @@ Indicates that the browser is connected.

#### browser.newContext([options])
- `options` <[Object]>
- `ignoreHTTPSErrors` <?[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
- `bypassCSP` <?[boolean]> Toggles bypassing page's Content-Security-Policy.
- `viewport` <?[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
- `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy.
- `viewport` <[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.
- `userAgent` <?[string]> Specific user agent to use in this context.
- `javaScriptEnabled` <?[boolean]> Whether or not to enable or disable JavaScript in the context. Defaults to true.
- `userAgent` <[string]> Specific user agent to use in this context.
- `javaScriptEnabled` <[boolean]> Whether or not to enable or disable JavaScript in the context. Defaults to true.
- `timezoneId` <?[string]> Changes the timezone of the context. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs.
- `geolocation` <[Object]>
- `latitude` <[number]> Latitude between -90 and 90.
Expand Down Expand Up @@ -341,10 +341,13 @@ An example of overriding `Math.random` before the page loads:
```js
// preload.js
Math.random = () => 42;
```

// In your playwright script, assuming the preload.js file is in same folder
const preloadFile = fs.readFileSync('./preload.js', 'utf8');
await browserContext.addInitScript(preloadFile);
```js
// In your playwright script, assuming the preload.js file is in same folder.
await browserContext.addInitScript({
path: 'preload.js'
});
```

> **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.
Expand Down Expand Up @@ -391,7 +394,7 @@ If URLs are specified, only cookies that affect those URLs are returned.

#### browserContext.exposeFunction(name, playwrightFunction)
- `name` <[string]> Name of the function on the window object.
- `playwrightFunction` <[function]> Callback function which will be called in Playwright's context.
- `playwrightFunction` <[function]> Callback function that will be called in the Playwright's context.
- returns: <[Promise]>

The method adds a function called `name` on the `window` object of every frame in every page in the context.
Expand Down Expand Up @@ -426,36 +429,6 @@ const crypto = require('crypto');
})();
```

An example of adding a `window.readfile` function to all pages in the context:

```js
const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
const fs = require('fs');

(async () => {
const browser = await chromium.launch();
const context = await browser.newContext();
await context.exposeFunction('readfile', async filePath => {
return new Promise((resolve, reject) => {
fs.readFile(filePath, 'utf8', (err, text) => {
if (err)
reject(err);
else
resolve(text);
});
});
});
const page = await context.newPage();
page.on('console', msg => console.log(msg.text()));
await page.evaluate(async () => {
// use window.readfile to read contents of a file
const content = await window.readfile('/etc/hosts');
console.log(content);
});
await browser.close();
})();
```

#### browserContext.newPage()
- returns: <[Promise]<[Page]>>

Expand Down Expand Up @@ -551,13 +524,13 @@ The extra HTTP headers will be sent with every request initiated by any page in
- `accuracy` <[number]> Optional non-negative accuracy value.
- returns: <[Promise]>

Sets the page's geolocation. Passing null or undefined emulates position unavailable.
Sets the contexts's geolocation. Passing null or undefined emulates position unavailable.

```js
await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
```

> **NOTE** Consider using [browserContext.setPermissions](#browsercontextsetpermissions-permissions) to grant permissions for the page to read its geolocation.
> **NOTE** Consider using [browserContext.setPermissions](#browsercontextsetpermissions-permissions) to grant permissions for the browser context pages to read its geolocation.
#### browserContext.setHTTPCredentials(httpCredentials)
- `httpCredentials` <?[Object]>
Expand Down Expand Up @@ -3346,7 +3319,7 @@ Aborts request. To use this, request interception should be enabled with `page.r
Exception is immediately thrown if the request interception is not enabled.

#### request.continue([overrides])
- `overrides` <[Object]> Optional request overwrites, which can be one of the following:
- `overrides` <[Object]> Optional request overrides, which can be one of the following:
- `method` <[string]> If set changes the request method (e.g. GET or POST)
- `postData` <[string]> If set changes the post data of request
- `headers` <[Object]> If set changes the request HTTP headers. Header values will be converted to a string.
Expand All @@ -3370,10 +3343,10 @@ await page.route('**/*', request => {
- returns: <?[Object]> Object describing request failure, if any
- `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.

The method returns `null` unless this request was failed, as reported by
The method returns `null` unless this request has failed, as reported by
`requestfailed` event.

Example of logging all failed requests:
Example of logging of all the failed requests:

```js
page.on('requestfailed', request => {
Expand Down Expand Up @@ -3473,7 +3446,7 @@ ResourceType will be one of the following: `document`, `stylesheet`, `image`, `m
[Response] class represents responses which are received by page.

<!-- GEN:toc -->
- [response.buffer()](#responsebuffer)
- [response.body()](#responsebody)
- [response.finished()](#responsefinished)
- [response.frame()](#responseframe)
- [response.headers()](#responseheaders)
Expand All @@ -3486,11 +3459,11 @@ ResourceType will be one of the following: `document`, `stylesheet`, `image`, `m
- [response.url()](#responseurl)
<!-- GEN:stop -->

#### response.buffer()
#### response.body()
- returns: <Promise<[Buffer]>> Promise which resolves to a buffer with response body.

#### response.finished()
- returns: <Promise[?string]> Waits for this response to finish, throws when corresponding request failed.
- returns: <Promise<?[Error]>> Waits for this response to finish, returns failure error if request failed.

#### response.frame()
- returns: <[Frame]> A [Frame] that initiated this response.
Expand Down Expand Up @@ -3743,7 +3716,7 @@ Closes the browser gracefully and makes sure the process is terminated.
Kills the browser process.

#### browserServer.process()
- returns: <?[ChildProcess]> Spawned browser application process.
- returns: <[ChildProcess]> Spawned browser application process.

#### browserServer.wsEndpoint()
- returns: <[string]> Browser websocket url.
Expand Down Expand Up @@ -3773,15 +3746,15 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
- [browserType.errors](#browsertypeerrors)
- [browserType.executablePath()](#browsertypeexecutablepath)
- [browserType.launch([options])](#browsertypelaunchoptions)
- [browserType.launchPersistent(userDataDir, [options])](#browsertypelaunchpersistentuserdatadir-options)
- [browserType.launchPersistentContext(userDataDir, [options])](#browsertypelaunchpersistentcontextuserdatadir-options)
- [browserType.launchServer([options])](#browsertypelaunchserveroptions)
- [browserType.name()](#browsertypename)
<!-- GEN:stop -->

#### browserType.connect(options)
- `options` <[Object]>
- `wsEndpoint` <?[string]> A browser websocket endpoint to connect to.
- `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on.
- `wsEndpoint` <[string]> A browser websocket endpoint to connect to.
- `slowMo` <?[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.
- returns: <[Promise]<[Browser]>>

This methods attaches Playwright to an existing browser instance.
Expand Down Expand Up @@ -3842,9 +3815,9 @@ try {
#### browserType.launch([options])
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:
- `headless` <[boolean]> Whether to run browser in headless mode. More details for [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the `devtools` option is `true`.
- `executablePath` <[string]> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, Firefox or WebKit, use at your own risk.
- `executablePath` <[string]> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). Note that Playwright [only works](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, Firefox or WebKit, use at your own risk.
- `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
- `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`browserType.defaultArgs()`](#browsertypedefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`.
- `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, Playwright does not pass its own configurations args and only uses the ones from `args`. If an array is given, then filters out the given default arguments. Dangerous option; use with care. Defaults to `false`.
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
- `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`.
Expand All @@ -3871,7 +3844,7 @@ const browser = await chromium.launch({ // Or 'firefox' or 'webkit'.
>
> See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
#### browserType.launchPersistent(userDataDir, [options])
#### browserType.launchPersistentContext(userDataDir, [options])
- `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile).
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:
- `headless` <[boolean]> Whether to run browser in headless mode. More details for [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the `devtools` option is `true`.
Expand All @@ -3887,7 +3860,7 @@ const browser = await chromium.launch({ // Or 'firefox' or 'webkit'.
- `devtools` <[boolean]> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
- returns: <[Promise]<[BrowserContext]>> Promise which resolves to the browser app instance.

Launches browser instance that uses persistent storage located at `userDataDir`. If `userDataDir` is not specified, temporary folder is created for the persistent storage. That folder is deleted when browser closes.
Launches browser instance that uses persistent storage located at `userDataDir`.

#### browserType.launchServer([options])
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:
Expand Down Expand Up @@ -4223,7 +4196,7 @@ const { chromium } = require('playwright');
(async () => {
const pathToExtension = require('path').join(__dirname, 'my-extension');
const userDataDir = '/tmp/test-user-data-dir';
const browserContext = await chromium.launchPersistent(userDataDir,{
const browserContext = await chromium.launchPersistentContext(userDataDir,{
headless: false,
args: [
`--disable-extensions-except=${pathToExtension}`,
Expand Down
4 changes: 2 additions & 2 deletions src/network.ts
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@ export class Response {
return this._finishedPromise;
}

buffer(): Promise<platform.BufferType> {
body(): Promise<platform.BufferType> {
if (!this._contentPromise) {
this._contentPromise = this._finishedPromise.then(async error => {
if (error)
Expand All @@ -296,7 +296,7 @@ export class Response {
}

async text(): Promise<string> {
const content = await this.buffer();
const content = await this.body();
return content.toString('utf8');
}

Expand Down
2 changes: 1 addition & 1 deletion src/server/browserType.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ export interface BrowserType {
name(): string;
launch(options?: LaunchOptions & { slowMo?: number }): Promise<Browser>;
launchServer(options?: LaunchOptions & { port?: number }): Promise<BrowserServer>;
launchPersistent(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext>;
launchPersistentContext(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext>;
connect(options: ConnectOptions): Promise<Browser>;
downloadBrowserIfNeeded(progress?: OnProgressCallback): Promise<void>;
devices: types.Devices;
Expand Down
4 changes: 2 additions & 2 deletions src/server/chromium.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ export class Chromium implements BrowserType {

async launch(options?: LaunchOptions & { slowMo?: number }): Promise<CRBrowser> {
if (options && (options as any).userDataDir)
throw new Error('userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistent` instead');
throw new Error('userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistentContext` instead');
const { browserServer, transport } = await this._launchServer(options, 'local');
const browser = await CRBrowser.connect(transport!, false, options && options.slowMo);
(browser as any)['__server__'] = browserServer;
Expand All @@ -64,7 +64,7 @@ export class Chromium implements BrowserType {
return (await this._launchServer(options, 'server', undefined, options && options.port)).browserServer;
}

async launchPersistent(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext> {
async launchPersistentContext(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext> {
const { timeout = 30000 } = options || {};
const { transport } = await this._launchServer(options, 'persistent', userDataDir);
const browser = await CRBrowser.connect(transport!, true);
Expand Down
4 changes: 2 additions & 2 deletions src/server/firefox.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ export class Firefox implements BrowserType {

async launch(options?: LaunchOptions & { slowMo?: number }): Promise<FFBrowser> {
if (options && (options as any).userDataDir)
throw new Error('userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistent` instead');
throw new Error('userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistentContext` instead');
const browserServer = await this._launchServer(options, 'local');
const browser = await platform.connectToWebsocket(browserServer.wsEndpoint()!, transport => {
return FFBrowser.connect(transport, false, options && options.slowMo);
Expand All @@ -77,7 +77,7 @@ export class Firefox implements BrowserType {
return await this._launchServer(options, 'server', undefined, options && options.port);
}

async launchPersistent(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext> {
async launchPersistentContext(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext> {
const { timeout = 30000 } = options || {};
const browserServer = await this._launchServer(options, 'persistent', userDataDir);
const browser = await platform.connectToWebsocket(browserServer.wsEndpoint()!, transport => {
Expand Down
4 changes: 2 additions & 2 deletions src/server/webkit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ export class WebKit implements BrowserType {

async launch(options?: LaunchOptions & { slowMo?: number }): Promise<WKBrowser> {
if (options && (options as any).userDataDir)
throw new Error('userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistent` instead');
throw new Error('userDataDir option is not supported in `browserType.launch`. Use `browserType.launchPersistentContext` instead');
const { browserServer, transport } = await this._launchServer(options, 'local');
const browser = await WKBrowser.connect(transport!, options && options.slowMo);
(browser as any)['__server__'] = browserServer;
Expand All @@ -76,7 +76,7 @@ export class WebKit implements BrowserType {
return (await this._launchServer(options, 'server', undefined, options && options.port)).browserServer;
}

async launchPersistent(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext> {
async launchPersistentContext(userDataDir: string, options?: LaunchOptions): Promise<BrowserContext> {
const { timeout = 30000 } = options || {};
const { transport } = await this._launchServer(options, 'persistent', userDataDir);
const browser = await WKBrowser.connect(transport!, undefined, true);
Expand Down
2 changes: 1 addition & 1 deletion test/chromium/launcher.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
describe('extensions', () => {
it('should return background pages', async() => {
const userDataDir = await makeUserDataDir();
const context = await playwright.launchPersistent(userDataDir, extensionOptions);
const context = await playwright.launchPersistentContext(userDataDir, extensionOptions);
const backgroundPages = await context.backgroundPages();
let backgroundPage = backgroundPages.length
? backgroundPages[0]
Expand Down
4 changes: 2 additions & 2 deletions test/defaultbrowsercontext.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,10 @@ module.exports.describe = function ({ testRunner, expect, defaultBrowserOptions,
const {it, fit, xit, dit} = testRunner;
const {beforeAll, beforeEach, afterAll, afterEach} = testRunner;

describe('launchPersistent()', function() {
describe('launchPersistentContext()', function() {
beforeEach(async state => {
state.userDataDir = await makeUserDataDir();
state.browserContext = await playwright.launchPersistent(state.userDataDir, defaultBrowserOptions);
state.browserContext = await playwright.launchPersistentContext(state.userDataDir, defaultBrowserOptions);
state.page = await state.browserContext.newPage();
});
afterEach(async state => {
Expand Down
Loading

0 comments on commit b43f33f

Please sign in to comment.