feat: speedup initializing MetaMask

.github/workflows/main.yml

@@ -33,6 +33,8 @@ jobs:
         with:
           name: debug_screenshots
           path: ./*.png
+      - name: Tests UserData
+        run: 'xvfb-run --auto-servernum --server-args="-screen 0, 1920x1080x24" yarn run test:${{matrix.automation}}:userData --timeout 240000'
   lint:
     name: Lint
     runs-on: ubuntu-latest

.gitignore

@@ -7,4 +7,6 @@ dist
 /.metamask
 .idea
 *.log
-*.png
+*.png
+
+!userData/**/*.log

docs/API.md

@@ -8,7 +8,7 @@ For additional information read root [readme](../README.md)
 - [Bootstrap dAppeteer](#bootstrap)
 - [Initialize Snap Environment](#initSnapEnv)
 - [Get MetaMask Window](#getMetaMask)
-- [metaMask methods](#methods)
+- [MetaMask methods](#methods)
   - [switchAccount](#switchAccount)
   - [importPK](#importPK)
   - [lock](#lock)
@@ -38,23 +38,26 @@ For additional information read root [readme](../README.md)
 # dAppeteer setup methods
 
 <a name="launch"></a>
-## `dappeteer.launch(puppeteerLib: typeof puppeteer, options: OfficialOptions | CustomOptions): Promise<Browser>`
+## `dappeteer.launch(options: DappeteerLaunchOptions): Promise<DappeteerBrowser>`
 ```typescript
-interface OfficialOptions {
-  metaMaskVersion: 'latest' | string;
+type DappeteerLaunchOptions = {
+  metaMaskVersion?:
+          | "latest"
+          | "local"
+          | string;
   metaMaskLocation?: Path;
-};
-
-type Path = string | { download: string; extract: string; };
-```
-or
-```typescript
-interface CustomOptions {
-  metaMaskPath: string;
+  metaMaskPath?: string;
+  metaMaskFlask?: boolean;
+  automation?: "puppeteer" | "playwright";
+  browser: "chrome";
+  puppeteerOptions?: Parameters<typeof puppeteerLaunch>[0];
+  playwrightOptions?: PlaywrightLaunchOptions;
+  userDataDir?: string;
+  key?: string;
 };
 ```
 
-returns an instance of `browser` same as `puppeteer.launch`, but it also installs the MetaMask extension. [It supports all the regular `puppeteer.launch` options](https://github.com/puppeteer/puppeteer/blob/v5.5.0/docs/api.md#puppeteerlaunchoptions)
+returns an instance of `DappeteerBrowser` for more information visit [browser page](docs/BROWSER.md)
 
 <a name="setup"></a>
 ## `dappeteer.setupMetaMask(browser: Browser, options: MetaMaskOptions = {}, steps: Step[]): Promise<Dappeteer>`
@@ -91,6 +94,8 @@ type DappeteerLaunchOptions = {
   browser: "chrome";
   puppeteerOptions?: Omit<Parameters<typeof puppeteerLaunch>[0], "headless">;
   playwrightOptions?: Omit<PlaywrightLaunchOptions, "headless">;
+  userDataDir?: string;
+  key?: string;
 };
 
 type MetaMaskOptions = {
@@ -139,7 +144,7 @@ it runs `dappeteer.launch` and `dappeteer.setupMetamask` and `snaps.installSnap`
 ## `dappeteer.getMetaMaskWindow(browser: Browser, version?: string): Promise<Dappeteer>`
 
 <a name="methods"></a>
-# metaMask methods
+# MetaMask methods
 `metaMask` is used as placeholder for dAppeteer returned by [`setupMetaMask`](setup) or [`getMetaMaskWindow`](getMetaMask)
 
 <a name="switchAccount"></a>

docs/BROWSER.md

@@ -0,0 +1,163 @@
+# dAppeteer Browser
+
+- [Methods](#methods)
+  - [isMetaMaskFlask](#isMetaMaskFlask)
+  - [pages](#pages)
+  - [newPage](#newPage)
+  - [getSource](#getSource)
+  - [close](#close)
+  - [wsEndpoint](#wsEndpoint)
+  - [getUserDataDirPath](#getUserDataDirPath)
+  - [storeUserData](#storeUserData)
+- [Advance Usages](#advanced)
+  - [Storing and lunching browser from specific state](#storeAndRun)
+    - [Storing state](#storeAndRun-storing)
+    - [Starting from state](#storeAndRun-start)
+
+<a name="methods"></a>
+# dAppeteer Browser methods
+
+<a name="isMetaMaskFlask"></a>
+## `browser.isMetaMaskFlask(): boolean`
+returns if browser runs MetaMask flask version
+
+<a name="pages"></a>
+## `browser.pages(): Promise<DappeteerPage<Page>[]>`
+returns list of open DappeteerPages
+
+<a name="newPage"></a>
+## `browser.newPage(): Promise<DappeteerPage<Page>>`
+open new blank page in browser and return DappeteerPage of it
+
+<a name="getSource"></a>
+## `browser.getSource(): Browser`
+returns underlying browser instance of browser runner
+
+<a name="close"></a>
+## `browser.close(): Promise<void>`
+it closes browser and clears temporary data
+
+<a name="wsEndpoint"></a>
+## `browser.wsEndpoint(): string`
+returns web socket address
+
+<a name="getUserDataDirPath"></a>
+## `browser.getUserDataDirPath(): string`
+return path of temporary dir of browsers user data
+
+<a name="storeUserData"></a>
+## `browser.storeUserData(destination: string): boolean`
+copy current user data on desired destination
+
+<a name="advanced"></a>
+# Advanced usages
+
+<a name="storeAndRun"></a>
+## Storing and lunching browser from specific state
+In situations when you want to skip setup or have state to fallback.  
+For an example, you can look at [`test/userData.spec.ts`](../test/userData.spec.ts)
+
+<a name="storeAndRun-storing"></a>
+### Storing state
+There is few approach's storing a state.  
+Best one is with help with using browser method [`browser.storeUserData`](#storeUserData).
+
+```js
+import dappeteer from "@chainsafe/dappeteer";
+
+async function store() {
+  const { metaMask, browser } = await dappeteer.bootstrap();
+
+  const dappPage = browser.newPage();
+  await dappPage.goto("https://chainsafe.io/");
+
+  // add custom network to a MetaMask
+  dappPage.evaluate(() => {
+    window.ethereum.request({
+      method: "wallet_addEthereumChain",
+      params: [
+        {
+          chainId: "0xa",
+          chainName: "Optimism",
+          nativeCurrency: {
+            name: "ETH",
+            symbol: "ETH", // 2-6 characters long
+            decimals: 18,
+          },
+          rpcUrls: ["https://mainnet.optimism.io"],
+        },
+      ],
+    });
+  });
+  await metaMask.acceptAddNetwork(true);
+
+  // add custom token to a MetaMask
+  dappPage.evaluate(() => {
+    window.ethereum.request({
+      method: "wallet_watchAsset",
+      params: {
+        type: "ERC20",
+        options: {
+          address: "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58",
+          symbol: "USDT",
+          decimals: 18,
+        },
+      },
+    });
+  });
+  await metaMask.acceptAddToken();
+
+  // we are almost ready to store state
+  // but at first we need to give a bit of time to metamask to store state
+  await dappPage.waitForTimeout(1000);
+
+  // now we can store on desiered location
+  browser.storeUserData("./location-path");
+
+  // done!
+  await browser.close();
+}
+
+store();
+```
+
+<a name="storeAndRun-start"></a>
+### Starting from state
+For loading state from a stored configuration just need to include option `userDataDir` with path to a previously stored state. 
+
+```js
+import dappeteer from "@chainsafe/dappeteer";
+
+async function resume() {
+  const { metaMask, browser } = await dappeteer.bootstrap({
+    userDataDir: "./location-path",
+  });
+
+  const dappPage = browser.newPage();
+  await dappPage.goto("https://chainsafe.io/");
+
+  // done!
+}
+
+resume();
+```
+
+dAppeteer provides state for default `MetaMaskOptions` to get path for it, you need to use constants `DEFAULT_METAMASK_USERDATA` and for a flask
+`DEFAULT_FLASK_USERDATA`.
+
+```js
+import dappeteer from "@chainsafe/dappeteer";
+
+async function resume() {
+  const { metaMask, browser } = await dappeteer.bootstrap({
+    userDataDir: dappeteer.DEFAULT_METAMASK_USERDATA,
+  });
+
+  const dappPage = browser.newPage();
+  await dappPage.goto("https://chainsafe.io/");
+
+  // done!
+}
+
+resume();
+```

package.json

@@ -16,6 +16,9 @@
     "build": "tsc -p tsconfig.build.json",
     "lint": "eslint --color --ext .ts src/ test/",
     "lint:fix": "yarn run lint --fix",
+    "test:userData": "USER_DATA_TEST=true mocha --bail --require ts-node/register",
+    "test:puppeteer:userData": "AUTOMATION=puppeteer yarn run test:userData",
+    "test:playwright:userData": "AUTOMATION=playwright yarn run test:userData",
     "test:mm": "mocha --bail --require ts-node/register --require test/global.ts",
     "test:flask": "mocha --bail --require ts-node/register --require test/global_flask.ts",
     "test:puppeteer:mm": "AUTOMATION=puppeteer yarn run test:mm",
@@ -42,6 +45,7 @@
   "license": "MIT",
   "dependencies": {
     "@metamask/providers": "^9.1.0",
+    "fs-extra": "^11.1.0",
     "node-stream-zip": "^1.13.0",
     "serve-handler": "5.0.8",
     "strict-event-emitter": "^0.2.8"
@@ -55,6 +59,7 @@
     "@rushstack/eslint-patch": "^1.2.0",
     "@types/chai": "^4.2.22",
     "@types/chai-as-promised": "^7.1.5",
+    "@types/fs-extra": "^9.0.13",
     "@types/mocha": "^9.1.1",
     "@types/serve-handler": "^6.1.1",
     "chai": "^4.3.4",

src/browser.ts

@@ -14,4 +14,8 @@ export interface DappeteerBrowser<Browser = unknown, Page = unknown>
   close(): Promise<void>;
 
   wsEndpoint(): string;
+
+  getUserDataDirPath(): string;
+
+  storeUserData(destination: string): boolean;
 }

src/constants.ts

@@ -1 +1,15 @@
+import path from "path";
+import { getDappateerPath } from "./helpers/utils";
+
 export const EXAMPLE_WEBSITE = "http://example.org";
+
+export const RECOMMENDED_METAMASK_VERSION = "v10.23.0";
+
+export const DEFAULT_METAMASK_USERDATA = path.join(
+  getDappateerPath(),
+  "userData/chrome-mm"
+);
+export const DEFAULT_FLASK_USERDATA = path.join(
+  getDappateerPath(),
+  "userData/chrome-flask"
+);

src/helpers/utils.ts

@@ -1,3 +1,5 @@
+import path from "path";
+
 export async function retry<R>(
   fn: () => Promise<R>,
   count: number
@@ -12,3 +14,11 @@ export async function retry<R>(
   }
   throw error;
 }
+
+export function getDappateerPath(): string {
+  try {
+    return path.dirname(require.resolve("@chainsafe/dappeteer/package.json"));
+  } catch {
+    return path.resolve();
+  }
+}

src/index.ts

@@ -8,4 +8,8 @@ export * from "./setup";
 export { DapeteerJestConfig } from "./jest/global";
 
 // default constants
-export const RECOMMENDED_METAMASK_VERSION = "v10.23.0";
+export {
+  RECOMMENDED_METAMASK_VERSION,
+  DEFAULT_METAMASK_USERDATA,
+  DEFAULT_FLASK_USERDATA,
+} from "./constants";

src/jest/DappeteerEnvironment.ts

@@ -4,6 +4,7 @@ import puppeteer from "puppeteer";
 
 import { getMetaMaskWindow } from "../index";
 import { DPuppeteerBrowser } from "../puppeteer";
+import { getTemporaryUserDataDir } from "../setup/utils/getTemporaryUserDataDir";
 
 class DappeteerEnvironment extends NodeEnvironment {
   constructor(config: Config.ProjectConfig) {
@@ -14,18 +15,20 @@ class DappeteerEnvironment extends NodeEnvironment {
     await super.setup();
 
     // get the wsEndpoint
-    const wsEndpoint = process.env.PUPPETEER_WS_ENDPOINT;
+    const wsEndpoint = process.env.DAPPETEER_WS_ENDPOINT;
     if (!wsEndpoint) {
       throw new Error("wsEndpoint not found");
     }
+    const userData =
+      process.env.DAPPETEER_USER_DATA_PATH || getTemporaryUserDataDir();
 
     // connect to puppeteer
     const browser = await puppeteer.connect({
       browserWSEndpoint: wsEndpoint,
     });
     this.global.browser = browser;
     this.global.metamask = await getMetaMaskWindow(
-      new DPuppeteerBrowser(browser, false)
+      new DPuppeteerBrowser(browser, userData, false)
     );
     this.global.page = await browser.newPage();
   }

src/jest/setup.ts

@@ -14,5 +14,6 @@ export default async function (): Promise<void> {
     console.log(error);
     throw error;
   }
-  process.env.PUPPETEER_WS_ENDPOINT = browser.wsEndpoint();
+  process.env.DAPPETEER_WS_ENDPOINT = browser.wsEndpoint();
+  process.env.DAPPETEER_USER_DATA_PATH = browser.getUserDataDirPath();
 }