1 | # How to Contribute
|
2 |
|
3 | First of all, thank you for your interest in Puppeteer!
|
4 | We'd love to accept your patches and contributions!
|
5 |
|
6 | ## Contributor License Agreement
|
7 |
|
8 | Contributions to this project must be accompanied by a Contributor License
|
9 | Agreement. You (or your employer) retain the copyright to your contribution,
|
10 | this simply gives us permission to use and redistribute your contributions as
|
11 | part of the project. Head over to <https://cla.developers.google.com/> to see
|
12 | your current agreements on file or to sign a new one.
|
13 |
|
14 | You generally only need to submit a CLA once, so if you've already submitted one
|
15 | (even if it was for a different project), you probably don't need to do it
|
16 | again.
|
17 |
|
18 | ## Getting setup
|
19 |
|
20 | 1. Clone this repository
|
21 | ```bash
|
22 | git clone https://github.com/GoogleChrome/puppeteer
|
23 | cd puppeteer
|
24 | ```
|
25 | 2. Install dependencies
|
26 | ```bash
|
27 | yarn # or 'npm install'
|
28 | ```
|
29 |
|
30 | ## Code reviews
|
31 |
|
32 | All submissions, including submissions by project members, require review. We
|
33 | use GitHub pull requests for this purpose. Consult
|
34 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
|
35 | information on using pull requests.
|
36 |
|
37 | ## Code Style
|
38 |
|
39 | - coding style is fully defined in [.eslintrc](https://github.com/GoogleChrome/puppeteer/blob/master/.eslintrc.js)
|
40 | - code should be annotated with [closure annotations](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler)
|
41 | - comments should be generally avoided. If the code would not be understood without comments, consider re-writing the code to make it self-explanatory
|
42 |
|
43 | To run code linter, use:
|
44 | ```
|
45 | npm run lint
|
46 | ```
|
47 |
|
48 | ## Writing Documentation
|
49 |
|
50 | 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.
|
51 |
|
52 | To run documentation linter, use
|
53 | ```
|
54 | npm run doc
|
55 | ```
|
56 |
|
57 | ## Adding New Dependencies
|
58 |
|
59 | For all dependencies (both installation and development):
|
60 | - **Do not add** a dependency if the desired functionality is easily implementable
|
61 | - if adding a dependency, it should be well-maintained and trustworthy
|
62 |
|
63 | A barrier for introducing new installation dependencies is especially high:
|
64 | - **do not add** installation dependency unless it's critical to project success
|
65 |
|
66 | ## Writing Tests
|
67 |
|
68 | - every feature should be accompanied by a test
|
69 | - every public api event/method should be accompanied by a test
|
70 | - tests should be *hermetic*. Tests should not depend on external services.
|
71 | - tests should work on all three platforms: Mac, Linux and Win. This is especially important for screenshot tests.
|
72 |
|
73 | Puppeteer tests are located in [test/test.js](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
|
74 | and are written using [Jasmine](https://jasmine.github.io/) testing framework. Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
|
75 |
|
76 | - To run all tests:
|
77 | ```
|
78 | npm run unit
|
79 | ```
|
80 | - To filter tests by name:
|
81 | ```
|
82 | npm run unit -- --filter=waitFor
|
83 | ```
|
84 | - To run a specific test, substitute the `it` with `fit` (mnemonic rule: '*focus it*'):
|
85 | ```js
|
86 | ...
|
87 | // Using "fit" to run specific test
|
88 | fit('should work', SX(async function() {
|
89 | await response = page.goto(EMPTY_PAGE);
|
90 | expect(response.ok).toBe(true);
|
91 | }))
|
92 | ```
|
93 | - To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '*cross it*'):
|
94 | ```js
|
95 | ...
|
96 | // Using "xit" to skip specific test
|
97 | xit('should work', SX(async function() {
|
98 | await response = page.goto(EMPTY_PAGE);
|
99 | expect(response.ok).toBe(true);
|
100 | }))
|
101 | ```
|
102 | - To run tests in non-headless mode:
|
103 | ```
|
104 | HEADLESS=false npm run unit
|
105 | ```
|
106 | - To run tests with custom Chromium executable:
|
107 | ```
|
108 | CHROME=<path-to-executable> npm run unit
|
109 | ```
|
110 | - To run tests in slow-mode:
|
111 | ```
|
112 | HEADLESS=false SLOW_MO=500 npm run unit
|
113 | ```
|
114 | - To debug a test, "focus" a test first and then run:
|
115 | ```
|
116 | npm run debug-unit
|
117 | ```
|
118 |
|
119 | There are also phantomjs tests located under [third_party/phantomjs/test](https://github.com/GoogleChrome/puppeteer/tree/master/third_party/phantomjs). These
|
120 | are used to test `phantom_shim`.
|
121 |
|
122 | ## Public API Coverage
|
123 |
|
124 | Every public API method or event should be called at least once in tests. To ensure this, there's a coverage command which tracks calls to public API and reports back if some methods/events were not called.
|
125 |
|
126 | Run coverage:
|
127 |
|
128 | ```
|
129 | npm run coverage
|
130 | ```
|
131 |
|
132 | ## Debugging Puppeteer
|
133 | 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 in a file called `script.js` and running it via `DEBUG=* node script.js`:
|
134 |
|
135 | ```js
|
136 | const puppeteer = require('puppeteer');
|
137 |
|
138 | (async() => {
|
139 |
|
140 | const browser = await puppeteer.launch();
|
141 | const page = await browser.newPage();
|
142 | await page.goto('https://example.com');
|
143 | browser.close();
|
144 |
|
145 | })();
|
146 | ```
|
147 |
|
148 | Tips-n-tricks:
|
149 | - `DEBUG=*:session node script.js` - dump protocol session messages (protocol messages to targets)
|
150 | - `DEBUG=*,-*:protocol node script.js` - dump everything BUT protocol messages
|
151 | - `DEBUG=*:page node script.js` - dump only Page's API calls
|
152 | - `DEBUG=*:mouse,*:keyboard node script.js` - dump only Mouse and Keyboard API calls
|