111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# How to Contribute
|
|
|
|
First of all, thank you for your interest in Puppeteer!
|
|
We'd love to accept your patches and contributions!
|
|
|
|
## Contributor License Agreement
|
|
|
|
Contributions to this project must be accompanied by a Contributor License
|
|
Agreement. You (or your employer) retain the copyright to your contribution,
|
|
this simply gives us permission to use and redistribute your contributions as
|
|
part of the project. Head over to <https://cla.developers.google.com/> to see
|
|
your current agreements on file or to sign a new one.
|
|
|
|
You generally only need to submit a CLA once, so if you've already submitted one
|
|
(even if it was for a different project), you probably don't need to do it
|
|
again.
|
|
|
|
## Code reviews
|
|
|
|
All submissions, including submissions by project members, require review. We
|
|
use GitHub pull requests for this purpose. Consult
|
|
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
|
|
information on using pull requests.
|
|
|
|
## Code Style
|
|
|
|
- coding style is fully defined in [.eslintrc](https://github.com/GoogleChrome/puppeteer/blob/master/.eslintrc.js). Please make sure to run `npm run lint` before submitting PR
|
|
- code should be annotated with [closure annotations](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler)
|
|
- comments should be generally avoided. If the code would not be understood without comments, consider re-writing the code to make it self-explanatory
|
|
|
|
## 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) that:
|
|
- makes sure documentation is aligned with the codebase
|
|
- generates up-to-date table-of-contents
|
|
|
|
To run the linter, use
|
|
```
|
|
npm run doc
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
For all dependencies (both installation and development):
|
|
- **Do not add** a dependency if the desired functionality is easily implementable in scope of the project
|
|
- if adding a dependency, it should be well-maintained and trustworthy
|
|
|
|
For installation dependencies:
|
|
- **do not add** installation dependency unless it's critical to project success
|
|
|
|
## Tests
|
|
|
|
- every feature should be accompanied by a test
|
|
- every public api event/method should be accompanied by a test
|
|
- tests should be *hermetic*. They should not require internet connection or depend on external services.
|
|
- tests should work on all three platforms: Mac, Linux and Win. This is especially important for screenshot tests.
|
|
|
|
Puppeteer tests are located in [test/test.js](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
|
|
and are written using [Jasmine](https://jasmine.github.io/) testing framework.
|
|
|
|
- To run all tests:
|
|
```
|
|
npm run unit
|
|
```
|
|
- To filter tests by name:
|
|
```
|
|
npm run unit -- --filter=waitFor
|
|
```
|
|
- To run a specific test, substitute the `it` with `fit` (mnemonic rule: '*focus it*'):
|
|
```js
|
|
...
|
|
// Using "fit" to run specific test
|
|
fit('should work', SX(function() {
|
|
await response = page.navigate(EMPTY_PAGE);
|
|
expect(response.ok).toBe(true);
|
|
}))
|
|
```
|
|
- To run tests in non-headless mode:
|
|
```
|
|
HEADLESS=false npm run unit
|
|
```
|
|
- To debug a test, "focus" a test first and then run
|
|
```
|
|
npm run debug-unit
|
|
```
|
|
|
|
There are also phantomjs tests located under [third_party/phantomjs/test](https://github.com/GoogleChrome/puppeteer/tree/master/third_party/phantomjs). These
|
|
are used to test `phantom_shim`.
|
|
|
|
## Public API Coverage
|
|
|
|
Every public API method should be called at least once during `npm run unit` command.
|
|
To ensure this, there's a `npm run coverage` command which tracks public API usage and reports back if some methods were not called.
|
|
|
|
## Debugging
|
|
Puppeteer uses [DEBUG](https://github.com/visionmedia/debug) module to expose some of it's inner guts under the `puppeteer` namespace.
|
|
Try putting the following script in the `script.js` and running it via `DEBUG=* node script.js`:
|
|
|
|
```js
|
|
const {Browser} = require('puppeteer');
|
|
const browser = new Browser();
|
|
browser.newPage().then(async page => {
|
|
await page.navigate('https://example.com');
|
|
browser.close();
|
|
});
|
|
```
|
|
|
|
Tips-n-tricks:
|
|
- `DEBUG=*,-*:protocol node script.js` - dump everything BUT protocol messages
|
|
- `DEBUG=*:page node script.js` - dump only Page's API calls
|
|
- `DEBUG=*:mouse,*:keyboard node script.js` - dump only Mouse and Keyboard API calls |