docs: add migration guide

Author: straker

README.md

@@ -29,7 +29,7 @@ So instead you decided to pin to the `@latest` tag. This works great as now both
 
 This is why this package exists. It will help keep the versions of Chrome and ChromeDriver in-sync so that your continuous integration system tests don't fail due to ChromeDriver versions. 
 
-So now instead of relying on pinning, you can ask the system which version of Chrome is installed and always get the version of ChromeDriver that matches. This will even work for Chrome channels that are not just Stable (i.e. Beta, Dev, and Canary).
+So now instead of relying on pinning, you can install the desired version of Chrome and Chromedriver. This will even work for Chrome channels that are not just Stable (i.e. Beta, Dev, and Canary).
 
 Here's an example of doing just that in an npm script.
 
@@ -46,22 +46,52 @@ If you wanted to install Chrome Beta and its associated driver:
 ```json
 {
   "scripts": {
-    "install:chromedriver": "browser-driver-manager install chrome@beta"
+    "install:chrome": "browser-driver-manager install chrome@beta"
   }
 }
 ```
 
+Once installed, a directory is created in your home directory called `.browser-driver-manager`. The directory will contain a `.env` file which will list the install path of both Chrome and Chromedriver under `CHROME_TEST_PATH` and `CHROMEDRIVER_TEST_PATH` respectively. 
+
+```
+# ~/.browser-driver-manager/.env
+CHROME_TEST_PATH=".browser-driver-manager/chrome/mac_arm-125.0.6422.141/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+CHROMEDRIVER_TEST_PATH=".browser-driver-manager/chromedriver/mac_arm-125.0.6422.141/chromedriver-mac-arm64/chromedriver"
+```
+
+To use the Chrome or Chromedriver binaries, you'll have to read the contents of the file and grab the path to the desired path. For example, using [dotenv](https://www.npmjs.com/package/dotenv) you can do the following:
+
+```js
+require('dotenv').config({ path: '~/.browser-driver-manager/.env' })
+```
+
+## Migration from v1 to v2
+
+V1 use to detect the version of Chrome installed on the system and install the corresponding version of the [chromedriver npm package](https://www.npmjs.com/package/chromedriver). However this had problems as the chromedriver package wasn't always up-to-date with the latest version so when Chrome updated to the next version, the chromedriver package could lag behind and still cause out-of-sync issues. Additionally the chromedriver package didn't always have the latest versions of non-stable channels so asking for Chrome Canary wasn't always reliable.
+
+V2 uses the newly released [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) to manage Chrome. This enables both installing specific versions of Chrome and fixes the previous chromedriver package issue. V2 utilizes the [`puppeteer/browser`](https://pptr.dev/browsers-api) script to manage the installation of Chrome and Chromedriver as it can handle downloading the binaries (and the multiple changes to the chromedriver download URL). This means that v2 no longer uses the chromedriver npm package to get chromedriver.
+
+This means in v2 you'll need to grab the Chromedriver path from the `~/.browser-driver-manager/.env` file and not from the chromedriver npm package. Additionally, you'll need to grab the Chrome path pass the path to any browser driver, such as Webdriver.
+
+Here's an example of grabbing the Chromedriver path in v1 and the change for v2.
+
+```js
+// v1
+const chromedriver = require('chromedriver');
+console.log(chromedriver.path);
+
+// v2
+require('dotenv').config({ path: '.browser-driver-manager/.env' })
+console.log(process.env.CHROMEDRIVER_TEST_PATH);
+```
+
 ## Supported Platforms and Browsers
 
 MacOS, Linux, and Windows platforms, and Chrome browser and drivers are supported. Firefox support is planned. 
 
 ## System Requirements
 
-Node is required to run commands.
-
-Install dependencies with
-
-`npm install`
+Node is required to run the commands.
 
 ## Commands and Options
 
@@ -77,19 +107,22 @@ Install dependencies with
     # Install latest Chrome Beta and matching Chromedriver
     browser-driver-manager install chrome@beta
 
+    # Install ChromeDriver version 97 and matching Chromedriver
+    browser-driver-manager install chrome@97
+
 - **version:** 
     Get the installed version of the browser or driver.
 
     ```bash
     # Get installed Chrome and Chromedriver versions
-    browser-driver-manager version
+    browser-driver-manager version chrome
 
 - **which:** 
     Get the installed location of the browser and driver.
 
     ```bash
     # Get installed Chrome and Chromedriver locations
-    browser-driver-manager which
+    browser-driver-manager which chrome
     ```
 
 ### Options

src/browser-driver-manager.js

@@ -75,11 +75,11 @@ async function setEnv({ chromePath, chromedriverPath, version }) {
   try {
     await fsPromises.writeFile(
       envPath,
-      `CHROME_TEST_PATH="${chromePath}"${os.EOL}CHROMEDRIVER_TEST_PATH="${chromedriverPath}"${os.EOL}VERSION="${version}"${os.EOL}`
+      `CHROME_TEST_PATH="${chromePath}"${os.EOL}CHROMEDRIVER_TEST_PATH="${chromedriverPath}"${os.EOL}CHROME_TEST_VERSION="${version}"${os.EOL}`
+    );
+    console.log(
+      `CHROME_TEST_PATH="${chromePath}"${os.EOL}CHROMEDRIVER_TEST_PATH="${chromedriverPath}"${os.EOL}CHROME_TEST_VERSION="${version}"${os.EOL}`
     );
-    console.log('CHROME_TEST_PATH is set in', chromePath);
-    console.log('CHROMEDRIVER_TEST_PATH is set in', chromedriverPath);
-    console.log('VERSION:', version);
   } catch (e) {
     throw new ErrorWithSuggestion(
       `Error setting CHROME/CHROMEDRIVER_TEST_PATH/VERSION. Ensure that the environment file at ${envPath} is writable.`,
@@ -121,7 +121,7 @@ async function which() {
  * @throws {Error} - Environment file must have valid version.
  */
 async function getVersion(suppressErrors = false) {
-  const pattern = /^VERSION="([\d.]+)"$/m;
+  const pattern = /^CHROME_TEST_VERSION="([\d.]+)"$/m;
   const env = await getEnv();
 
   if (!env) {
@@ -139,7 +139,7 @@ async function getVersion(suppressErrors = false) {
       return null;
     }
     throw new Error(
-      `No version found in the environment file. Either remove the environment file and reinstall, or add a line 'VERSION={YOUR_INSTALLED_VERSION} to it.`
+      `No version found in the environment file. Either remove the environment file and reinstall, or add a line 'CHROME_TEST_VERSION={YOUR_INSTALLED_VERSION} to it.`
     );
   }
 

test/index.js

@@ -19,7 +19,7 @@ const MOCK_BDM_CACHE_DIR = path.resolve(
 const envPath = path.resolve(MOCK_BDM_CACHE_DIR, '.env');
 const chromeTestPath = `${MOCK_BDM_CACHE_DIR}/chrome/os_arch-${mockVersion}/chrome`;
 const chromedriverTestPath = `${MOCK_BDM_CACHE_DIR}/chromedriver/os_arch-${mockVersion}/chromedriver`;
-const envContents = `CHROME_TEST_PATH="${chromeTestPath}"${os.EOL}CHROMEDRIVER_TEST_PATH="${chromedriverTestPath}"${os.EOL}VERSION="${mockVersion}"`;
+const envContents = `CHROME_TEST_PATH="${chromeTestPath}"${os.EOL}CHROMEDRIVER_TEST_PATH="${chromedriverTestPath}"${os.EOL}CHROME_TEST_VERSION="${mockVersion}"`;
 const noVersionEnvContents = `CHROME_TEST_PATH="${chromeTestPath}"${os.EOL}CHROMEDRIVER_TEST_PATH="${chromedriverTestPath}"${os.EOL}"`;
 
 const mockResolveBuildId = sinon.stub();
@@ -91,8 +91,11 @@ let consoleLogStub;
 
 const wrapConsoleLogStub = async fn => {
   consoleLogStub = sinon.stub(console, 'log');
-  await fn();
-  consoleLogStub.restore();
+  try {
+    await fn();
+  } finally {
+    consoleLogStub.restore();
+  }
 };
 
 describe('browser-driver-manager', () => {