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 | ## Commit Messages
|
49 |
|
50 | Commit messages should follow the Semantic Commit Messages format:
|
51 |
|
52 | ```
|
53 | label(namespace): title
|
54 |
|
55 | description
|
56 |
|
57 | footer
|
58 | ```
|
59 |
|
60 | 1. *label* is one of the following:
|
61 | - `fix` - puppeteer bug fixes
|
62 | - `feat` - puppeteer features
|
63 | - `docs` - changes to docs, e.g. `docs(api.md): ..` to change documentation
|
64 | - `test` - changes to puppeteer tests infrastructure
|
65 | - `style` - puppeteer code style: spaces/alignment/wrapping etc
|
66 | - `chore` - build-related work, e.g. doclint changes / travis / appveyor
|
67 | 1. *namespace* is put in parenthesis after label and is optional
|
68 | 2. *title* is a brief summary of changes
|
69 | 3. *description* is **optional**, new-line separated from title and is in present tense
|
70 | 4. *footer* is **optional**, new-line separated from *description* and contains "fixes" / "references" attribution to github issues
|
71 | 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.
|
72 |
|
73 | Example:
|
74 |
|
75 | ```
|
76 | fix(Page): fix page.pizza method
|
77 |
|
78 | This patch fixes page.pizza so that it works with iframes.
|
79 |
|
80 | Fixes #123, Fixes #234
|
81 |
|
82 | BREAKING CHANGE: page.pizza now delivers pizza at home by default.
|
83 | To deliver to a different location, use "deliver" option:
|
84 | `page.pizza({deliver: 'work'})`.
|
85 | ```
|
86 |
|
87 |
|
88 | ## Writing Documentation
|
89 |
|
90 | 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.
|
91 |
|
92 | To run documentation linter, use
|
93 | ```
|
94 | npm run doc
|
95 | ```
|
96 |
|
97 | ## Adding New Dependencies
|
98 |
|
99 | For all dependencies (both installation and development):
|
100 | - **Do not add** a dependency if the desired functionality is easily implementable
|
101 | - if adding a dependency, it should be well-maintained and trustworthy
|
102 |
|
103 | A barrier for introducing new installation dependencies is especially high:
|
104 | - **do not add** installation dependency unless it's critical to project success
|
105 |
|
106 | ## Writing Tests
|
107 |
|
108 | - every feature should be accompanied by a test
|
109 | - every public api event/method should be accompanied by a test
|
110 | - tests should be *hermetic*. Tests should not depend on external services.
|
111 | - tests should work on all three platforms: Mac, Linux and Win. This is especially important for screenshot tests.
|
112 |
|
113 | Puppeteer tests are located in [test/test.js](https://github.com/GoogleChrome/puppeteer/blob/master/test/test.js)
|
114 | and are written with a [TestRunner](https://github.com/GoogleChrome/puppeteer/tree/master/utils/testrunner) framework.
|
115 | Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
|
116 |
|
117 | - To run all tests:
|
118 | ```
|
119 | npm run unit
|
120 | ```
|
121 | - To filter tests by name:
|
122 | ```
|
123 | npm run unit -- --filter=waitFor
|
124 | ```
|
125 | - To run a specific test, substitute the `it` with `fit` (mnemonic rule: '*focus it*'):
|
126 | ```js
|
127 | ...
|
128 | // Using "fit" to run specific test
|
129 | fit('should work', SX(async function() {
|
130 | const response = await page.goto(EMPTY_PAGE);
|
131 | expect(response.ok).toBe(true);
|
132 | }))
|
133 | ```
|
134 | - To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '*cross it*'):
|
135 | ```js
|
136 | ...
|
137 | // Using "xit" to skip specific test
|
138 | xit('should work', SX(async function() {
|
139 | const response = await page.goto(EMPTY_PAGE);
|
140 | expect(response.ok).toBe(true);
|
141 | }))
|
142 | ```
|
143 | - To run tests in non-headless mode:
|
144 | ```
|
145 | HEADLESS=false npm run unit
|
146 | ```
|
147 | - To run tests with custom Chromium executable:
|
148 | ```
|
149 | CHROME=<path-to-executable> npm run unit
|
150 | ```
|
151 | - To run tests in slow-mode:
|
152 | ```
|
153 | HEADLESS=false SLOW_MO=500 npm run unit
|
154 | ```
|
155 | - To debug a test, "focus" a test first and then run:
|
156 | ```
|
157 | npm run debug-unit
|
158 | ```
|
159 |
|
160 | ## Public API Coverage
|
161 |
|
162 | 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.
|
163 |
|
164 | Run coverage:
|
165 |
|
166 | ```
|
167 | npm run coverage
|
168 | ```
|
169 |
|
170 | ## Debugging Puppeteer
|
171 | See [Debugging Tips](README.md#debugging-tips) in the readme
|
172 |
|