Skip to content

Commit

Permalink
chore: Spelling and Markdown Consistency (puppeteer#1998)
Browse files Browse the repository at this point in the history
- Adding missing language tags to markdown code blocks.
- Fixed various spelling mistakes my IDE complained to me about.
  • Loading branch information
Drew Diamantoukos authored and aslushnikov committed Feb 9, 2018
1 parent 070243e commit b275e66
Show file tree
Hide file tree
Showing 12 changed files with 92 additions and 74 deletions.
63 changes: 44 additions & 19 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,16 @@ again.
## Getting setup

1. Clone this repository

```bash
git clone https://github.com/GoogleChrome/puppeteer
cd puppeteer
```
2. Install dependencies

2. Install dependencies

```bash
yarn # or 'npm install'
npm install
```

## Code reviews
Expand All @@ -41,7 +44,8 @@ information on using pull requests.
- comments should be generally avoided. If the code would not be understood without comments, consider re-writing the code to make it self-explanatory

To run code linter, use:
```

```bash
npm run lint
```

Expand Down Expand Up @@ -73,11 +77,11 @@ footer
- `test` - changes to puppeteer tests infrastructure
- `style` - puppeteer code style: spaces/alignment/wrapping etc
- `chore` - build-related work, e.g. doclint changes / travis / appveyor
1. *namespace* is put in parenthesis after label and is optional
2. *title* is a brief summary of changes
3. *description* is **optional**, new-line separated from title and is in present tense
4. *footer* is **optional**, new-line separated from *description* and contains "fixes" / "references" attribution to github issues
5. *footer* should also include "BREAKING CHANGE" if current API clients will break due to this change. It should explain what changed and how to get the old behavior.
2. *namespace* is put in parenthesis after label and is optional
3. *title* is a brief summary of changes
4. *description* is **optional**, new-line separated from title and is in present tense
5. *footer* is **optional**, new-line separated from *description* and contains "fixes" / "references" attribution to github issues
6. *footer* should also include "BREAKING CHANGE" if current API clients will break due to this change. It should explain what changed and how to get the old behavior.

Example:

Expand All @@ -93,13 +97,13 @@ To deliver to a different location, use "deliver" option:
`page.pizza({deliver: 'work'})`.
```


## Writing Documentation

All public API should have a descriptive entry in the [docs/api.md](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md). There's a [documentation linter](https://github.com/GoogleChrome/puppeteer/tree/master/utils/doclint) which makes sure documentation is aligned with the codebase.

To run documentation linter, use
```

```bash
npm run doc
```

Expand All @@ -110,7 +114,7 @@ For all dependencies (both installation and development):
- if adding a dependency, it should be well-maintained and trustworthy

A barrier for introducing new installation dependencies is especially high:
- **do not add** installation dependency unless it's critical to project success
- **Do not add** installation dependency unless it's critical to project success

## Writing Tests

Expand All @@ -124,14 +128,25 @@ and are written with a [TestRunner](https://github.com/GoogleChrome/puppeteer/tr
Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.

- To run all tests:
```

```bash
npm run unit
```
- To run tests in parallel, use `-j` flag:

- To filter tests by name:

```bash
npm run unit --filter=waitFor
```

- To run tests in parallel, use `-j` flag:

```bash
npm run unit -- -j 4
```

- To run a specific test, substitute the `it` with `fit` (mnemonic rule: '*focus it*'):

```js
...
// Using "fit" to run specific test
Expand All @@ -140,7 +155,9 @@ npm run unit -- -j 4
expect(response.ok).toBe(true);
}))
```

- To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '*cross it*'):

```js
...
// Using "xit" to skip specific test
Expand All @@ -149,20 +166,28 @@ npm run unit -- -j 4
expect(response.ok).toBe(true);
}))
```

- To run tests in non-headless mode:
```

```bash
HEADLESS=false npm run unit
```

- To run tests with custom Chromium executable:
```

```bash
CHROME=<path-to-executable> npm run unit
```

- To run tests in slow-mode:
```

```bash
HEADLESS=false SLOW_MO=500 npm run unit
```

- To debug a test, "focus" a test first and then run:
```

```bash
node --inspect-brk test/test.js
```

Expand All @@ -172,10 +197,10 @@ Every public API method or event should be called at least once in tests. To ens

Run coverage:

```
```bash
npm run coverage
```

## Debugging Puppeteer
See [Debugging Tips](README.md#debugging-tips) in the readme

See [Debugging Tips](README.md#debugging-tips) in the readme
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Puppeteer
# Puppeteer

<!-- [START badges] -->
[![Linux Build Status](https://img.shields.io/travis/GoogleChrome/puppeteer/master.svg)](https://travis-ci.org/GoogleChrome/puppeteer) [![Windows Build Status](https://img.shields.io/appveyor/ci/aslushnikov/puppeteer/master.svg?logo=appveyor)](https://ci.appveyor.com/project/aslushnikov/puppeteer/branch/master) [![NPM puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer)
Expand Down Expand Up @@ -31,7 +31,8 @@ Give it a spin: https://try-puppeteer.appspot.com/
### Installation

To use Puppeteer in your project, run:
```

```bash
npm i --save puppeteer
# or "yarn add puppeteer"
```
Expand Down Expand Up @@ -131,8 +132,7 @@ const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'});

See [`Puppeteer.launch()`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) for more information.

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/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
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/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.

**3. Creates a fresh user profile**

Expand All @@ -154,23 +154,24 @@ Explore the [API documentation](docs/api.md) and [examples](https://github.com/G

const browser = await puppeteer.launch({headless: false});

1. Slow it down - the `slowMo` option slows down Puppeteer operations by the
2. Slow it down - the `slowMo` option slows down Puppeteer operations by the
specified amount of milliseconds. It's another way to help see what's going on.

const browser = await puppeteer.launch({
headless: false,
slowMo: 250 // slow down by 250ms
});

1. Capture console output - You can listen for the `console` event.
3. Capture console output - You can listen for the `console` event.
This is also handy when debugging code in `page.evaluate()`:

page.on('console', msg => console.log('PAGE LOG:', msg.text()));

await page.evaluate(() => console.log(`url is ${location.href}`));

await page.evaluate(() => console.log(`url is ${location.href}`));

1. Enable verbose logging - All public API calls and internal protocol traffic
4. Enable verbose logging - All public API calls and internal protocol traffic
will be logged via the [`debug`](https://github.com/visionmedia/debug) module under the `puppeteer` namespace.

# Basic verbose logging
Expand Down Expand Up @@ -218,8 +219,7 @@ See [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIB
The goals of the project are simple:

- Provide a slim, canonical library that highlights the capabilities of the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
- Provide a reference implementation for similar testing libraries. Eventually, these
other frameworks could adopt Puppeteer as their foundational layer.
- Provide a reference implementation for similar testing libraries. Eventually, these other frameworks could adopt Puppeteer as their foundational layer.
- Grow the adoption of headless/automated browser testing.
- Help dogfood new DevTools Protocol features...and catch bugs!
- Learn more about the pain points of automated browser testing and help fill those gaps.
Expand Down
50 changes: 20 additions & 30 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,6 @@ The Puppeteer API is hierarchical and mirrors the browser structure. On the foll

(Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing))


### Environment Variables

Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations. These variables can either be set in the environment or in the [npm config](https://docs.npmjs.com/cli/config).
Expand Down Expand Up @@ -315,14 +314,13 @@ This methods attaches Puppeteer to an existing Chromium instance.

The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed.

> **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no
guarantee it will work with any other version. Use `executablePath` option with extreme caution.
If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
> **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution.
>
> If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
>
> In [puppeteer.launch([options])](#puppeteerlaunchoptions) above, any mention of Chromium also applies to Chrome.
>
> 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/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
> 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/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
### class: BrowserFetcher

Expand Down Expand Up @@ -600,7 +598,6 @@ The method runs `document.querySelectorAll` within the page. If no elements matc

Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).


#### page.$$eval(selector, pageFunction[, ...args])
- `selector` <[string]> A [selector] to query frame for
- `pageFunction` <[function]> Function to be evaluated in browser context
Expand Down Expand Up @@ -775,8 +772,8 @@ puppeteer.launch().then(async browser => {
List of all available devices is available in the source code: [DeviceDescriptors.js](https://github.com/GoogleChrome/puppeteer/blob/master/DeviceDescriptors.js).

#### page.emulateMedia(mediaType)
- `mediaType` <?[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables media emulation.
- returns: <[Promise]>
- `mediaType` <?[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables media emulation.
- returns: <[Promise]>

#### page.evaluate(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
Expand Down Expand Up @@ -840,7 +837,6 @@ await resultHandle.dispose();

Shortcut for [page.mainFrame().executionContext().evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).


#### page.evaluateOnNewDocument(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
Expand Down Expand Up @@ -1124,16 +1120,16 @@ Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)]

#### page.screenshot([options])
- `options` <[Object]> Options object which might have the following properties:
- `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the image won't be saved to the disk.
- `type` <[string]> Specify screenshot type, can be either `jpeg` or `png`. Defaults to 'png'.
- `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images.
- `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. Defaults to `false`.
- `clip` <[Object]> An object which specifies clipping region of the page. Should have the following fields:
- `x` <[number]> x-coordinate of top-left corner of clip area
- `y` <[number]> y-coordinate of top-left corner of clip area
- `width` <[number]> width of clipping area
- `height` <[number]> height of clipping area
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
- `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the image won't be saved to the disk.
- `type` <[string]> Specify screenshot type, can be either `jpeg` or `png`. Defaults to 'png'.
- `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images.
- `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. Defaults to `false`.
- `clip` <[Object]> An object which specifies clipping region of the page. Should have the following fields:
- `x` <[number]> x-coordinate of top-left corner of clip area
- `y` <[number]> y-coordinate of top-left corner of clip area
- `width` <[number]> width of clipping area
- `height` <[number]> height of clipping area
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
- returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot

#### page.select(selector, ...values)
Expand Down Expand Up @@ -1409,7 +1405,6 @@ puppeteer.launch().then(async browser => {
```
Shortcut for [page.mainFrame().waitForXPath(xpath[, options])](#framewaitforxpathxpath-options).


### class: Keyboard

Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
Expand Down Expand Up @@ -1897,7 +1892,6 @@ This method behaves differently with respect to the type of the first parameter:
- if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
- otherwise, an exception is thrown


#### frame.waitForFunction(pageFunction[, options[, ...args]])
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters
Expand Down Expand Up @@ -2160,10 +2154,10 @@ The method evaluates the XPath expression relative to the elementHandle. If ther

#### elementHandle.boundingBox()
- returns: <[Promise]<?[Object]>>
- x <[number]> the x coordinate of the element in pixels.
- y <[number]> the y coordinate of the element in pixels.
- width <[number]> the width of the element in pixels.
- height <[number]> the height of the element in pixels.
- x <[number]> the x coordinate of the element in pixels.
- y <[number]> the y coordinate of the element in pixels.
- width <[number]> the width of the element in pixels.
- height <[number]> the height of the element in pixels.

This method returns the bounding box of the element (relative to the main frame), or `null` if the element is not visible.

Expand Down Expand Up @@ -2459,7 +2453,6 @@ Identifies what kind of target this is. Can be `"page"`, `"service_worker"`, or
#### target.url()
- returns: <[string]>


### class: CDPSession

* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
Expand Down Expand Up @@ -2492,7 +2485,6 @@ to send messages.
- `params` <[Object]> Optional method parameters
- returns: <[Promise]<[Object]>>


### class: Coverage

Coverage gathers information about parts of JavaScript and CSS that were used by the page.
Expand Down Expand Up @@ -2544,7 +2536,6 @@ console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);

> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.

#### coverage.stopJSCoverage()
- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all non-anonymous scripts
- `url` <[string]> Script URL
Expand All @@ -2556,7 +2547,6 @@ console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);
> **NOTE** JavaScript Coverage doesn't include anonymous scripts. However, scripts with sourceURLs are
reported.


[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean"
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
Expand Down
5 changes: 3 additions & 2 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ xorg-x11-fonts-misc
- make sure kernel version is up-to-date
- read about linux sandbox here: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md
- try running without the sandbox (**Note: running without the sandbox is not recommended due to security reasons!**)

```js
const browser = await puppeteer.launch({args: ['--no-sandbox', '--disable-setuid-sandbox']});
```
Expand All @@ -101,7 +102,7 @@ shared library dependencies.
To fix, you'll need to install the missing dependencies and the
latest Chromium package in your Dockerfile:

```
```Dockerfile
FROM node:8-slim

# See https://crbug.com/795759
Expand Down Expand Up @@ -168,7 +169,7 @@ The [newest Chromium package](https://pkgs.alpinelinux.org/package/edge/communit

Example Dockerfile:

```
```Dockerfile
FROM node:9-alpine

# Installs latest Chromium (63) package.
Expand Down
Loading

0 comments on commit b275e66

Please sign in to comment.