chromedriver 137.0.1 → 137.0.2

package/README.md

@@ -7,13 +7,13 @@ An NPM wrapper for Selenium [ChromeDriver](https://sites.google.com/chromium.org
 
 ## Building and Installing
 
-```shell
+```bash
 npm install chromedriver
 ```
 
 Or grab the source and
 
-```shell
+```bash
 node ./install.js
 ```
 
@@ -25,30 +25,87 @@ The package has been set up to fetch and run ChromeDriver for MacOS (darwin),
 Linux based platforms (as identified by Node.js), and Windows.  If you
 spot any platform weirdness, let us know or send a patch.
 
-## Force download
+## Configuration Methods
 
-By default this package, when installed, will search for an existing
-Chromedriver binary in your configured temp directory. If found, and it is the
-correct version, it will simply copy it to your node_modules directory. You can
-force it always download by configuring it:
+You can configure chromedriver using any of the following methods. The installer will check all of these, in order of
+precedence:
+
+- Environment variables in uppercase (e.g., `CHROMEDRIVER_VERSION`)
+- `package.json#config` in lowercase
+- `.npmrc` entries in lowercase (e.g., `chromedriver_version=LATEST`)
+
+This applies to all options such as:
 
-```shell
-npm install chromedriver --chromedriver-force-download
+- `chromedriver_version`
+- `chromedriver_cdnurl`
+- `chromedriver_cdnbinariesurl`
+- `chromedriver_legacy_cdnurl`
+- `chromedriver_skip_download`
+- `chromedriver_force_download`
+- `chromedriver_filepath`
+- `detect_chromedriver_version`
+- `include_chromium`
+
+But not to native npm config options, which can be set as per
+[NPM's documentation](https://docs.npmjs.com/cli/using-npm/config).
+
+For example, to set the version, you can use:
+
+```bash
+CHROMEDRIVER_VERSION=LATEST npm install chromedriver
 ```
 
-Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
+Or in your package.json under `config`:
+
+```jsonc
+{
+  // ... other configuration
+  "config": {
+    "chromedriver_version": "LATEST"
+  }
+}
+```
+
+You can also add it to your `.npmrc` when using NPM up to version 11,
+but the NPM team is
+[discouraging it](https://github.com/npm/cli/issues/8153)
+and it won't work on version 12+:
 
 ```ini
-chromedriver_force_download=true
+chromedriver_version=LATEST
+```
+
+The same goes to using arguments, it will work up to version 11:
+
+```bash
+npm install chromedriver --chromedriver_version=LATEST
+```
+
+These last two way to configure the installation will be removed from this package a few months after the NPM
+team removes support for them.
+
+### Force download
+
+By default this package, when installed, will search for an existing
+Chromedriver binary in your configured temp directory. If found, and it is the
+correct version, it will simply copy it to your node_modules directory. You can
+force it to always download by configuring it in your package.json under `config`:
+
+```json
+{
+  "config": {
+    "chromedriver_force_download": "true"
+  }
+}
 ```
 
 Another option is to use PATH variable `CHROMEDRIVER_FORCE_DOWNLOAD`.
 
-```shell
+```bash
 CHROMEDRIVER_FORCE_DOWNLOAD=true npm install chromedriver
 ```
 
-## Custom binaries url
+### Custom binaries url
 
 This allows you to use your own endpoints for metadata and binaries. It is useful in air gapped
 scenarios or if you have download restrictions, such as firewalls.
@@ -60,71 +117,77 @@ but implemented in this package starting with version
 [README.md](https://github.com/giggio/node-chromedriver/tree/114.0.1#custom-binaries-url)
 at the latest tag where it was using the legacy urls (`114.0.1`).
 
-### For versions >= 115
-
 There are two urls that need to be configured, one for metadata and one for binaries.
 The one for metadata is the "CDN url", and the one for binaries is the "CDN binaries url".
 See [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/) to understand
 how these urls work.
 
-Npm config:
+#### Config
 
-For metadata use `chromedriver_cdnurl`. The default is `https://googlechromelabs.github.io`. You need to either supply the binary download endpoint, or the binaries url config, see bellow.
+For metadata use `chromedriver_cdnurl`. The default is `https://googlechromelabs.github.io`. You need to either supply
+the binary download endpoint, or the binaries url config, see below.
 
 For binaries use `chromedriver_cdnbinariesurl`. The default is to search for the download url using
 `$chromedriver_cdnurl/chrome-for-testing/[version].json`, which forms a URL like:
-https://googlechromelabs.github.io/chrome-for-testing/122.0.6261.57.json.
+<https://googlechromelabs.github.io/chrome-for-testing/122.0.6261.57.json>.
 
 The resulting url will be something like:
-https://storage.googleapis.com/chrome-for-testing-public/122.0.6261.57/linux64/chromedriver-linux64.zip.
+<https://storage.googleapis.com/chrome-for-testing-public/122.0.6261.57/linux64/chromedriver-linux64.zip>.
 
 Keep in mind that this last url is just an example and it might change (as it has happened in the past).
 
-```shell
-npm install chromedriver --chromedriver_cdnurl=https://npmmirror.com/metadata --chromedriver_cdnbinariesurl=https://npmmirror.com/binaries
-```
-
-Or add these properties to your [`.npmrc`](https://docs.npmjs.com/cli/configuring-npm/npmrc) file:
-
-```ini
-chromedriver_cdnurl=https://npmmirror.com/metadata
-chromedriver_cdnbinariesurl=https://npmmirror.com/binaries
-```
-
-Another option is to use the environment variables `CHROMEDRIVER_CDNURL` and `CHROMEDRIVER_CDNBINARIESURL`.
+One option is to use the environment variables `CHROMEDRIVER_CDNURL` and `CHROMEDRIVER_CDNBINARIESURL`.
 
-```shell
+```bash
 CHROMEDRIVER_CDNURL=https://npmmirror.com/metadata CHROMEDRIVER_CDNBINARIESURL=https://npmmirror.com/binaries npm install chromedriver
 ```
 
-### For versions < 115
+Or add them to your `package.json`:
 
-There is one url to both metadata and binaries.
+```json
+{
+  "config": {
+    "chromedriver_cdnurl": "https://npmmirror.com/metadata",
+    "chromedriver_cdnbinariesurl": "https://npmmirror.com/binaries"
+  }
+}
+```
 
-To use a mirror of the ChromeDriver binaries use npm config property `chromedriver_legacy_cdnurl`.
-Default is `https://chromedriver.storage.googleapis.com`.
+Or use the legacy arguments:
 
-```shell
-npm install chromedriver --chromedriver_legacy_cdnurl=https://npmmirror.com/mirrors/chromedriver --chromedriver_version=LATEST_114
+```bash
+npm install chromedriver --chromedriver_cdnurl=https://npmmirror.com/metadata --chromedriver_cdnbinariesurl=https://npmmirror.com/binaries
 ```
 
-Or add a property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file:
+Or add these properties to your [`.npmrc`](https://docs.npmjs.com/cli/configuring-npm/npmrc) file:
 
 ```ini
-chromedriver_legacy_cdnurl=https://npmmirror.com/mirrors/chromedriver
+chromedriver_cdnurl=https://npmmirror.com/metadata
+chromedriver_cdnbinariesurl=https://npmmirror.com/binaries
 ```
 
-Another option is to use the environment variable `CHROMEDRIVER_LEGACY_CDNURL`.
+### Custom binaries file
 
-```shell
-CHROMEDRIVER_LEGACY_CDNURL=https://npmmirror.com/mirrors/chromedriver npm install chromedriver --chromedriver_version=LATEST_114
+To get the chromedriver from the filesystem instead of a web request use the npm config property `chromedriver_filepath`
+in your package.json under `config`:
+
+```json
+{
+  "config": {
+    "chromedriver_filepath": "/path/to/chromedriver_mac64.zip"
+  }
+}
 ```
 
-## Custom binaries file
+Or using the environment variable:
+
+```bash
+CHROMEDRIVER_FILEPATH=/path/to/chromedriver_mac64.zip npm install chromedriver
+```
 
-To get the chromedriver from the filesystem instead of a web request use the npm config property `chromedriver_filepath`.
+Or the legacy methods:
 
-```shell
+```bash
 npm install chromedriver --chromedriver_filepath=/path/to/chromedriver_mac64.zip
 ```
 
@@ -134,63 +197,192 @@ Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
 chromedriver_filepath=/path/to/chromedriver_mac64.zip
 ```
 
-Another option is to use the PATH variable `CHROMEDRIVER_FILEPATH`
-
-```shell
-CHROMEDRIVER_FILEPATH=/path/to/chromedriver_mac64.zip
-```
-
 This variable can be used to set either a `.zip` file or the binary itself, eg:
 
-```shell
+```bash
 CHROMEDRIVER_FILEPATH=/bin/chromedriver
 ```
-## Installing on RISC-V 64-bit Systems
+
+### Installing on RISC-V 64-bit Systems
+
 Chromedriver does not provide an official binary for RISC-V 64-bit architectures. To install on a RISC-V system, you must supply your own Chromedriver binary using the `--chromedriver_filepath` option. For example:
 
 ```bash
 npm install chromedriver --chromedriver_filepath=/path/to/chromedriver
 ```
-## Custom download options
+
+### Custom download options
 
 Install through a proxy.
 
-```shell
+```bash
 npm config set proxy http://[user:pwd]@domain.tld:port
 npm config set https-proxy http://[user:pwd]@domain.tld:port
 ```
 
 Use different User-Agent.
 
-```shell
+```bash
 npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"
 ```
 
-## Skipping chromedriver download
+### Skipping chromedriver download
 
 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.
 
-To achieve this you can use the npm config property `chromedriver_skip_download`.
+To achieve this you can use the config property `chromedriver_skip_download`, either via environment variable:
+
+```bash
+CHROMEDRIVER_SKIP_DOWNLOAD=true npm install chromedriver
+```
+
+Or in your package.json under `config`:
+
+```json
+{
+  "config": {
+    "chromedriver_skip_download": "true"
+  }
+}
+```
+
+Or using the legacy method, via argument:
 
-```shell
+```bash
 npm install chromedriver --chromedriver_skip_download=true
 ```
 
-Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
+Or adding a property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
 
 ```ini
 chromedriver_skip_download=true
 ```
 
-Another option is to use the PATH variable `CHROMEDRIVER_SKIP_DOWNLOAD`
+### Versioning
+
+The NPM package version tracks the version of chromedriver that will be installed,
+with an additional build number that is used for revisions to the installer.
+You can use the package version number to install a specific version, or use the
+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,
+use `LATEST` as the version number. In your package.json under `config`:
+
+```json
+{
+  "config": {
+    "chromedriver_version": "LATEST"
+  }
+}
+```
+
+Using the environment variable:
+
+```bash
+CHROMEDRIVER_VERSION=LATEST npm install chromedriver
+```
+
+Or using the legacy method:
+
+```bash
+npm install chromedriver --chromedriver_version=LATEST
+```
+
+Or adding the property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
+
+```ini
+chromedriver_version=LATEST
+```
+
+Another option is to use env variable `CHROMEDRIVER_VERSION`.
+
+```bash
+CHROMEDRIVER_VERSION=LATEST npm install chromedriver
+```
+
+You can force the latest release for a specific major version by specifying `LATEST_{VERSION_NUMBER}`:
+
+```bash
+CHROMEDRIVER_VERSION=LATEST_80 npm install chromedriver
+```
+
+You can also force a different version of chromedriver by replacing `LATEST` with a version number:
+
+```bash
+CHROMEDRIVER_VERSION=75.0.3770.140 npm install chromedriver
+```
+
+### Detect ChromeDriver Version
+
+The NPM package version may not be always compatible to your Chrome version.
+To get the chromedriver that corresponds to the version of Chrome installed,
+you can use the npm config property `detect_chromedriver_version`. In your package.json under `config`:
+
+```json
+{
+  "config": {
+    "detect_chromedriver_version": "true"
+  }
+}
+```
+
+Or using the environment variable:
+
+```bash
+DETECT_CHROMEDRIVER_VERSION=true npm install chromedriver
+```
+
+Or the legacy method with the argument:
+
+```bash
+npm install chromedriver --detect_chromedriver_version=true
+```
+
+Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
+
+```ini
+detect_chromedriver_version=true
+```
+
+**Note:** When the property `detect_chromedriver_version` is provided,
+`chromedriver_version` and `chromedriver_filepath` properties are ignored.
 
-```shell
-CHROMEDRIVER_SKIP_DOWNLOAD=true
+### Include Chromium
+
+If you don't have Chrome installed, you can check for Chromium version instead by setting the argument
+`include_chromium` to `true`. In your package.json under `config`:
+
+```json
+{
+  "config": {
+    "include_chromium": "true"
+  }
+}
 ```
 
+Or using the environment variable:
+
+```bash
+INCLUDE_CHROMIUM=true npm install chromedriver
+```
+
+Or using the legacy argument:
+
+```bash
+npm install chromedriver --include_chromium=true
+```
+
+Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
+
+```ini
+include_chromium=true
+```
+
+**Note:** The property `INCLUDE_CHROMIUM` is ignored if the property `DETECT_CHROMEDRIVER_VERSION` is not used.
+
 ## Running
 
-```shell
+```bash
 bin/chromedriver [arguments]
 ```
 
@@ -245,7 +437,6 @@ args = [
 chromedriver.start(args);
 // run your tests
 chromedriver.stop();
-
 ```
 
 With the latest version, you can optionally receive a Promise from the `chromedriver.start` function:
@@ -262,89 +453,6 @@ chromedriver
 Note: if your tests are ran asynchronously, chromedriver.stop() will have to be
 executed as a callback at the end of your tests
 
-## Versioning
-
-The NPM package version tracks the version of chromedriver that will be installed,
-with an additional build number that is used for revisions to the installer.
-You can use the package version number to install a specific version, or use the
-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,
-use `LATEST` as the version number:
-
-```shell
-npm install chromedriver --chromedriver_version=LATEST
-```
-
-Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
-
-```ini
-chromedriver_version=LATEST
-```
-
-Another option is to use env variable `CHROMEDRIVER_VERSION`.
-
-```shell
-CHROMEDRIVER_VERSION=LATEST npm install chromedriver
-```
-
-You can force the latest release for a specific major version by specifying `LATEST_{VERSION_NUMBER}`:
-
-```shell
-CHROMEDRIVER_VERSION=LATEST_80 npm install chromedriver
-```
-
-You can also force a different version of chromedriver by replacing `LATEST` with a version number:
-
-```shell
-CHROMEDRIVER_VERSION=75.0.3770.140 npm install chromedriver
-```
-
-## Detect ChromeDriver Version
-
-The NPM package version may not be always compatible to your Chrome version.
-To get the chromedriver that corresponds to the version of Chrome installed,
-you can use the npm config property `detect_chromedriver_version`.
-
-```shell
-npm install chromedriver --detect_chromedriver_version
-```
-
-Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
-
-```ini
-detect_chromedriver_version=true
-```
-
-Another option is to use environment variable `DETECT_CHROMEDRIVER_VERSION`.
-
-```shell
-DETECT_CHROMEDRIVER_VERSION=true npm install chromedriver
-```
-
-**Note:** When the property `detect_chromedriver_version` is provided,
-`chromedriver_version` and `chromedriver_filepath` properties are ignored.
-
-## Include Chromium
-
-If you don't have Chrome installed, you can check for Chromium version instead by setting the argument `include_chromium` to `true`.
-
-```shell
-npm install chromedriver --include_chromium
-```
-
-Or add property to your [`.npmrc`](https://docs.npmjs.com/files/npmrc) file.
-
-```ini
-include_chromium=true
-```
-
-Another option is to use environment variable `INCLUDE_CHROMIUM`.
-
-```shell
-INCLUDE_CHROMIUM=true npm install chromedriver
-```
-
-**Note:** The property `INCLUDE_CHROMIUM` is ignored if the property `DETECT_CHROMEDRIVER_VERSION` is not used.
-
 ## A Note on chromedriver
 
 Chromedriver is not a library for NodeJS.
@@ -357,7 +465,8 @@ It is not a Node.js wrapper.
 We will do our best to support every supported Node.js versions.
 See [nodejs/Release](https://github.com/nodejs/Release) for
 the current supported versions. You can also view our
-[build scripts](https://github.com/giggio/node-chromedriver/blob/main/.github/workflows/build.yml#L41) and check the versions there.
+[build scripts](https://github.com/giggio/node-chromedriver/blob/main/.github/workflows/build.yml#L41) and check the
+versions there.
 
 ## Contributing
 
@@ -376,7 +485,7 @@ If you are on Windows, set `git config core.autocrlf input` so you don't get git
 [Giovanni Bassi](https://github.com/giggio), with collaboration from
 [lots of good people](https://github.com/giggio/node-chromedriver/graphs/contributors).
 
-Thanks for Obvious and their PhantomJS project for heavy inspiration! Check their project on [Github](https://github.com/Obvious/phantomjs/).
+Thanks for the [PhantomJS](https://github.com/Medium/phantomjs) install project for heavy inspiration!
 
 ## License
 

package/install.js

@@ -17,20 +17,26 @@ const finishedAsync = promisify(finished);
 const process = require('node:process');
 const console = require('node:console');
 
+function getNpmEnvVar(name) {
+  return process.env[name.toUpperCase()] ??
+    process.env[`npm_package_config_${name}`] ??
+    process.env[`npm_config_${name}`];
+}
+
 class Installer {
   async install() {
-    const skipDownload = (process.env.npm_config_chromedriver_skip_download || process.env.CHROMEDRIVER_SKIP_DOWNLOAD) === 'true';
+    const skipDownload = (getNpmEnvVar('chromedriver_skip_download') === 'true');
     if (skipDownload) {
       console.log('Found CHROMEDRIVER_SKIP_DOWNLOAD variable, skipping installation.');
       process.exit(0);
     }
-    const cdnUrl = (process.env.npm_config_chromedriver_cdnurl || process.env.CHROMEDRIVER_CDNURL || 'https://googlechromelabs.github.io').replace(/\/+$/, '');
-    const legacyCdnUrl = (process.env.npm_config_chromedriver_legacy_cdnurl || process.env.CHROMEDRIVER_LEGACY_CDNURL || 'https://chromedriver.storage.googleapis.com').replace(/\/+$/, '');
-    let chromedriverVersion = process.env.npm_config_chromedriver_version || process.env.CHROMEDRIVER_VERSION || helper.version;
-    const detectChromedriverVersion = (process.env.npm_config_detect_chromedriver_version || process.env.DETECT_CHROMEDRIVER_VERSION) === 'true';
+    const cdnUrl = (getNpmEnvVar('chromedriver_cdnurl') || 'https://googlechromelabs.github.io').replace(/\/+$/, '');
+    const legacyCdnUrl = (getNpmEnvVar('chromedriver_legacy_cdnurl') || 'https://chromedriver.storage.googleapis.com').replace(/\/+$/, '');
+    let chromedriverVersion = getNpmEnvVar('chromedriver_version') || helper.version;
+    const detectChromedriverVersion = (getNpmEnvVar('detect_chromedriver_version') === 'true');
     try {
       if (detectChromedriverVersion) {
-        const includeChromium = (process.env.npm_config_include_chromium || process.env.INCLUDE_CHROMIUM) === 'true';
+        const includeChromium = (getNpmEnvVar('include_chromium') === 'true');
         // Refer http://chromedriver.chromium.org/downloads/version-selection
         const chromeVersion = await getChromeVersion(includeChromium);
         console.log("Your Chrome version is " + chromeVersion);
@@ -60,7 +66,7 @@ class Installer {
       const chromedriverIsAvailable = await this.verifyIfChromedriverIsAvailableAndHasCorrectVersion(chromedriverVersion, chromedriverBinaryFilePath);
       if (!chromedriverIsAvailable) {
         console.log('Current existing ChromeDriver binary is unavailable, proceeding with download and extraction.');
-        const configuredfilePath = process.env.npm_config_chromedriver_filepath || process.env.CHROMEDRIVER_FILEPATH;
+        const configuredfilePath = getNpmEnvVar('chromedriver_filepath');
         if (configuredfilePath) {
           console.log('Using file: ', configuredfilePath);
           downloadedFile = configuredfilePath;
@@ -92,7 +98,7 @@ class Installer {
         return 'linux64';
       } else if (process.arch === 'riscv64') {
         // Check if --chromedriver_filepath is provided via env vars
-        const configuredfilePath = process.env.npm_config_chromedriver_filepath || process.env.CHROMEDRIVER_FILEPATH;
+        const configuredfilePath = getNpmEnvVar('chromedriver_filepath');
         if (!configuredfilePath) {
           console.error(
             'Error: RISC-V detected: No official Chromedriver binary is available for RISC-V 64-bit. ' +
@@ -134,7 +140,7 @@ class Installer {
    * @param {string} platform
    */
   async downloadFile(cdnUrl, downloadedFile, chromedriverVersion, platform) {
-    const cdnBinariesUrl = (process.env.npm_config_chromedriver_cdnbinariesurl || process.env.CHROMEDRIVER_CDNBINARIESURL)?.replace(/\/+$/, '');
+    const cdnBinariesUrl = (getNpmEnvVar('chromedriver_cdnbinariesurl'))?.replace(/\/+$/, '');
     const url = cdnBinariesUrl
       ? `${cdnBinariesUrl}/${chromedriverVersion}/${platform}/${path.basename(downloadedFile)}`
       : await this.getDownloadUrl(cdnUrl, chromedriverVersion, platform);
@@ -176,7 +182,7 @@ class Installer {
   verifyIfChromedriverIsAvailableAndHasCorrectVersion(chromedriverVersion, chromedriverBinaryFilePath) {
     if (!fs.existsSync(chromedriverBinaryFilePath))
       return Promise.resolve(false);
-    const forceDownload = process.env.npm_config_chromedriver_force_download === 'true' || process.env.CHROMEDRIVER_FORCE_DOWNLOAD === 'true';
+    const forceDownload = getNpmEnvVar('chromedriver_force_download') === 'true';
     if (forceDownload)
       return Promise.resolve(false);
     console.log('ChromeDriver binary exists. Validating...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromedriver",
-  "version": "137.0.1",
+  "version": "137.0.2",
   "keywords": [
     "chromedriver",
     "selenium"