1 | # ChromeDriver
|
2 |
|
3 | [![Build Status](https://dev.azure.com/giggio/node-chromedriver/_apis/build/status/giggio.node-chromedriver?branchName=main)](https://dev.azure.com/giggio/node-chromedriver/_build?definitionId=27&_a=summary&repositoryFilter=15&branchFilter=49) [![Build Status](https://travis-ci.org/giggio/node-chromedriver.svg?branch=main)](https://travis-ci.org/giggio/node-chromedriver)
|
4 | [![npm](https://img.shields.io/npm/dt/chromedriver.svg)](https://www.npmjs.com/package/chromedriver)
|
5 |
|
6 | An NPM wrapper for Selenium [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/).
|
7 |
|
8 | ## Building and Installing
|
9 |
|
10 | ```shell
|
11 | npm install chromedriver
|
12 | ```
|
13 |
|
14 | Or grab the source and
|
15 |
|
16 | ```shell
|
17 | node ./install.js
|
18 | ```
|
19 |
|
20 | What this is really doing is just grabbing a particular "blessed" (by
|
21 | this module) version of ChromeDriver. As new versions are released
|
22 | and vetted, this module will be updated accordingly.
|
23 |
|
24 | The package has been set up to fetch and run ChromeDriver for MacOS (darwin),
|
25 | Linux based platforms (as identified by Node.js), and Windows. If you
|
26 | spot any platform weirdness, let us know or send a patch.
|
27 |
|
28 | ## Force download
|
29 |
|
30 | By default this package, when installed, will search for an existing
|
31 | Chromedriver binary in your configured temp directory. If found, and it is the
|
32 | correct version, it will simply copy it to your node_modules directory. You can
|
33 | force it always download by configuring it:
|
34 |
|
35 | ```shell
|
36 | npm install chromedriver --chromedriver-force-download
|
37 | ```
|
38 |
|
39 | Or add property into your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
|
40 |
|
41 | ```
|
42 | chromedriver_force_download=true
|
43 | ```
|
44 |
|
45 | Another option is to use PATH variable `CHROMEDRIVER_FORCE_DOWNLOAD`.
|
46 |
|
47 | ```shell
|
48 | CHROMEDRIVER_FORCE_DOWNLOAD=true npm install chromedriver
|
49 | ```
|
50 |
|
51 | ## Custom binaries url
|
52 |
|
53 | To use a mirror of the ChromeDriver binaries use npm config property `chromedriver_cdnurl`.
|
54 | Default is `https://chromedriver.storage.googleapis.com`.
|
55 |
|
56 | ```shell
|
57 | npm install chromedriver --chromedriver_cdnurl=https://npm.taobao.org/mirrors/chromedriver
|
58 | ```
|
59 |
|
60 | Or add property into your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
|
61 |
|
62 | ```
|
63 | chromedriver_cdnurl=https://npm.taobao.org/mirrors/chromedriver
|
64 | ```
|
65 |
|
66 | Another option is to use PATH variable `CHROMEDRIVER_CDNURL`.
|
67 |
|
68 | ```shell
|
69 | CHROMEDRIVER_CDNURL=https://npm.taobao.org/mirrors/chromedriver npm install chromedriver
|
70 | ```
|
71 |
|
72 | ## Custom binaries file
|
73 |
|
74 | To get the chromedriver from the filesystem instead of a web request use the npm config property `chromedriver_filepath`.
|
75 |
|
76 | ```shell
|
77 | npm install chromedriver --chromedriver_filepath=/path/to/chromedriver_mac64.zip
|
78 | ```
|
79 |
|
80 | Or add property into your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
|
81 |
|
82 | ```
|
83 | chromedriver_filepath=/path/to/chromedriver_mac64.zip
|
84 | ```
|
85 |
|
86 | Another option is to use the PATH variable `CHROMEDRIVER_FILEPATH`
|
87 |
|
88 | ```shell
|
89 | CHROMEDRIVER_FILEPATH=/path/to/chromedriver_mac64.zip
|
90 | ```
|
91 |
|
92 | This variable can be used to set either a `.zip` file or the binary itself, eg:
|
93 |
|
94 | ```shell
|
95 | CHROMEDRIVER_FILEPATH=/bin/chromedriver
|
96 | ```
|
97 |
|
98 | ## Custom download options
|
99 |
|
100 | Install through a proxy.
|
101 |
|
102 | ```shell
|
103 | npm config set proxy http://[user:pwd]@domain.tld:port
|
104 | npm config set https-proxy http://[user:pwd]@domain.tld:port
|
105 | ```
|
106 |
|
107 | Use different User-Agent.
|
108 |
|
109 | ```shell
|
110 | npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"
|
111 | ```
|
112 |
|
113 | ## Skipping chromedriver download
|
114 |
|
115 | You may wish to skip the downloading of the chromedriver binary file, for example if you know for certain that it is already there or if you want to use a system binary and just use this module as an interface to interact with it.
|
116 |
|
117 | To achieve this you can use the npm config property `chromedriver_skip_download`.
|
118 |
|
119 | ```shell
|
120 | npm install chromedriver --chromedriver_skip_download=true
|
121 | ```
|
122 |
|
123 | Or add property into your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
|
124 |
|
125 | ```
|
126 | chromedriver_skip_download=true
|
127 | ```
|
128 |
|
129 | Another option is to use the PATH variable `CHROMEDRIVER_SKIP_DOWNLOAD`
|
130 |
|
131 | ```shell
|
132 | CHROMEDRIVER_SKIP_DOWNLOAD=true
|
133 | ```
|
134 |
|
135 | ## Running
|
136 |
|
137 | ```shell
|
138 | bin/chromedriver [arguments]
|
139 | ```
|
140 |
|
141 | And npm will install a link to the binary in `node_modules/.bin` as
|
142 | it is wont to do.
|
143 |
|
144 | ## Running with Selenium WebDriver
|
145 |
|
146 | ```javascript
|
147 | require('chromedriver');
|
148 | var webdriver = require('selenium-webdriver');
|
149 | var driver = new webdriver.Builder()
|
150 | .forBrowser('chrome')
|
151 | .build();
|
152 | ```
|
153 |
|
154 | (Tested for selenium-webdriver version `2.48.2`)
|
155 |
|
156 | The path will be added to the process automatically, you don't need to configure it.
|
157 | But you can get it from `require('chromedriver').path` if you want it.
|
158 |
|
159 | ## Running via node
|
160 |
|
161 | The package exports a `path` string that contains the path to the
|
162 | chromedriver binary/executable.
|
163 |
|
164 | Below is an example of using this package via node.
|
165 |
|
166 | ```javascript
|
167 | var childProcess = require('child_process');
|
168 | var chromedriver = require('chromedriver');
|
169 | var binPath = chromedriver.path;
|
170 |
|
171 | var childArgs = [
|
172 | 'some argument'
|
173 | ];
|
174 |
|
175 | childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
|
176 | // handle results
|
177 | });
|
178 |
|
179 | ```
|
180 |
|
181 | You can also use the start and stop methods:
|
182 |
|
183 | ```javascript
|
184 | var chromedriver = require('chromedriver');
|
185 |
|
186 | args = [
|
187 | // optional arguments
|
188 | ];
|
189 | chromedriver.start(args);
|
190 | // run your tests
|
191 | chromedriver.stop();
|
192 |
|
193 | ```
|
194 |
|
195 | With the latest version, you can optionally receive a Promise from the `chromedriver.start` function:
|
196 |
|
197 | ```javascript
|
198 | var returnPromise = true;
|
199 | chromedriver
|
200 | .start(args, returnPromise)
|
201 | .then(() => {
|
202 | console.log('chromedriver is ready');
|
203 | });
|
204 | ```
|
205 |
|
206 | Note: if your tests are ran asynchronously, chromedriver.stop() will have to be
|
207 | executed as a callback at the end of your tests
|
208 |
|
209 | ## Versioning
|
210 |
|
211 | The NPM package version tracks the version of chromedriver that will be installed,
|
212 | with an additional build number that is used for revisions to the installer.
|
213 | You can use the package version number to install a specific version, or use the
|
214 | setting to a specific version. If there is a new Chromedriver version available which is not yet available as a version of `node-chromedriver`, the npm command `npm run update-chromedriver` in this repository can be used to make the required updates to this module, please submit the change as a PR. To always install the latest version of Chromedriver,
|
215 | use `LATEST` as the version number:
|
216 |
|
217 | ```shell
|
218 | npm install chromedriver --chromedriver_version=LATEST
|
219 | ```
|
220 |
|
221 | Or add property into your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
|
222 |
|
223 | ```
|
224 | chromedriver_version=LATEST
|
225 | ```
|
226 |
|
227 | Another option is to use env variable `CHROMEDRIVER_VERSION`.
|
228 |
|
229 | ```shell
|
230 | CHROMEDRIVER_VERSION=LATEST npm install chromedriver
|
231 | ```
|
232 |
|
233 | You can force the latest release for a specific major version by specifying `LATEST_{VERSION_NUMBER}`:
|
234 |
|
235 | ```shell
|
236 | CHROMEDRIVER_VERSION=LATEST_80 npm install chromedriver
|
237 | ```
|
238 |
|
239 | You can also force a different version of chromedriver by replacing `LATEST` with a version number:
|
240 |
|
241 | ```shell
|
242 | CHROMEDRIVER_VERSION=75.0.3770.140 npm install chromedriver
|
243 | ```
|
244 |
|
245 | ## Detect ChromeDriver Version
|
246 |
|
247 | The NPM package version may not be always compatible to your Chrome version.
|
248 | To get the chromedriver that corresponds to the version of Chrome installed,
|
249 | you can use the npm config property `detect_chromedriver_version`.
|
250 |
|
251 | ```shell
|
252 | npm install chromedriver --detect_chromedriver_version
|
253 | ```
|
254 |
|
255 | Or add property into your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
|
256 |
|
257 | ```
|
258 | detect_chromedriver_version=true
|
259 | ```
|
260 |
|
261 | Another option is to use environment variable `DETECT_CHROMEDRIVER_VERSION`.
|
262 |
|
263 | ```shell
|
264 | DETECT_CHROMEDRIVER_VERSION=true npm install chromedriver
|
265 | ```
|
266 |
|
267 | **Note:** When the property `detect_chromedriver_version` is provided,
|
268 | `chromedriver_version` and `chromedriver_filepath` properties are ignored.
|
269 |
|
270 | ## A Note on chromedriver
|
271 |
|
272 | Chromedriver is not a library for NodeJS.
|
273 |
|
274 | This is an _NPM wrapper_ and can be used to conveniently make ChromeDriver available.
|
275 | It is not a Node.js wrapper.
|
276 |
|
277 | ## Supported Node.js versions
|
278 |
|
279 | We will do our best to support every supported Node.js versions.
|
280 | See [nodejs/Release](https://github.com/nodejs/Release) for
|
281 | the current supported versions. You can also view our
|
282 | [build scripts](https://github.com/giggio/node-chromedriver/blob/main/azure-pipelines.yml) and check the versions there.
|
283 |
|
284 | ## Contributing
|
285 |
|
286 | Questions, comments, bug reports, and pull requests are all welcome. Submit them at
|
287 | [the project on GitHub](https://github.com/giggio/node-chromedriver/).
|
288 |
|
289 | Bug reports that include steps-to-reproduce (including code) are the
|
290 | best. Even better, make them in the form of pull requests.
|
291 |
|
292 | We have added
|
293 | [VS Code Remote support with containers](https://code.visualstudio.com/docs/remote/containers).
|
294 | If you are on Windows, set `git config core.autocrlf input` so you don't get git errors.
|
295 |
|
296 | ## Author
|
297 |
|
298 | [Giovanni Bassi](https://github.com/giggio), with collaboration from
|
299 | [lots of good people](https://github.com/giggio/node-chromedriver/graphs/contributors).
|
300 |
|
301 | Thanks for Obvious and their PhantomJS project for heavy inspiration! Check their project on [Github](https://github.com/Obvious/phantomjs/).
|
302 |
|
303 | ## License
|
304 |
|
305 | Licensed under the Apache License, Version 2.0.
|