API.md

dAppeteer API

Methods provided by dAppeteer.
For additional information read root readme

• Launch dAppeteer
• Setup MetaMask
• Bootstrap dAppeteer
• Initialize Snap Environment
• Get MetaMask Window
• MetaMask methods
  • switchAccount
  • importPK
  • lock
  • unlock
  • switchNetwork
  • acceptAddNetwork
  • rejectAddNetwork
  • acceptAddToken
  • rejectAddToken
  • confirmTransaction
  • sign
  • signTypedData
  • approve
  • helpers
    • getTokenBalance
    • deleteAccount
    • deleteNetwork
  • page
  • snaps methods
    • installSnap
    • invokeSnap
    • getNotificationEmitter
    • getAllNotifications
    • dialog
      • accept
      • reject
      • type

dAppeteer setup methods

dappeteer.launch(options: DappeteerLaunchOptions): Promise<DappeteerBrowser>

type DappeteerLaunchOptions = {
  metaMaskVersion?:
          | "latest"
          | "local"
          | string;
  metaMaskLocation?: Path;
  metaMaskPath?: string;
  metaMaskFlask?: boolean;
  automation?: "puppeteer" | "playwright";
  puppeteerOptions?: Parameters<typeof puppeteerLaunch>[0];
  playwrightOptions?: PlaywrightLaunchOptions;
  userDataDir?: string;
  key?: string;
};

returns an instance of DappeteerBrowser for more information visit browser page

dappeteer.setupMetaMask(browser: Browser, options: MetaMaskOptions = {}, steps: Step[]): Promise<Dappeteer>

interface MetaMaskOptions {
  seed?: string;
  password?: string;
  showTestNets?: boolean;
}

type Step = (page: Page, options?: Options) => void;

`dappeteer.bootstrap(options: DappeteerLaunchOptions & MetaMaskOptions): Promise<{

metaMask: Dappeteer; browser: DappeteerBrowser; metaMaskPage: DappeteerPage; }>`

type DappeteerLaunchOptions = {
  metaMaskVersion?:
    | "latest"
    | "local"
    | string;
  metaMaskLocation?: Path;
  metaMaskPath?: string;
  metaMaskFlask?: boolean;
  automation?: "puppeteer" | "playwright";
  puppeteerOptions?: Omit<Parameters<typeof puppeteerLaunch>[0], "headless">;
  playwrightOptions?: Omit<PlaywrightLaunchOptions, "headless">;
  userDataDir?: string;
  key?: string;
};

type MetaMaskOptions = {
  seed?: string;
  password?: string;
  showTestNets?: boolean;
};

it runs dappeteer.launch and dappeteer.setupMetaMask and returns an object with metaMask, metaMaskPage and browser.

dappeteer.initSnapEnv( opts: DappeteerLaunchOptions & MetaMaskOptions & InstallSnapOptions & { snapIdOrLocation: string }): Promise<{ metaMask: Dappeteer; browser: DappeteerBrowser; metaMaskPage: DappeteerPage; snapId: string;}

type DappeteerLaunchOptions = {
  metaMaskVersion?:
    | "latest"
    | "local"
    | string;
  metaMaskLocation?: Path;
  metaMaskPath?: string;
  metaMaskFlask?: boolean;
  automation?: "puppeteer" | "playwright";
  browser: "chrome";
  puppeteerOptions?: Omit<Parameters<typeof puppeteerLaunch>[0], "headless">;
  playwrightOptions?: Omit<PlaywrightLaunchOptions, "headless">;
};

type MetaMaskOptions = {
  seed?: string;
  password?: string;
  showTestNets?: boolean;
};

type InstallSnapOptions = {
    customSteps?: InstallStep[];
    version?: string;
    installationSnapUrl?: string;
}

it runs dappeteer.launch and dappeteer.setupMetamask and snaps.installSnap and returns an object with metaMask, metaMaskPage, browser and snapId.

dappeteer.getMetaMaskWindow(browser: Browser, version?: string): Promise<Dappeteer>

MetaMask methods

metaMask is used as placeholder for dAppeteer returned by setupMetaMask or getMetaMaskWindow

metaMask.switchAccount(accountNumber: number): Promise<void>

it commands MetaMask to switch to a different account, by passing the index/position of the account in the accounts list.

metaMask.importPK(privateKey: string): Promise<void>

it commands MetaMask to import a private key. It can only be used while you haven't signed in yet, otherwise it throws.

metaMask.lock(): Promise<void>

signs out from MetaMask. It can only be used if you already signed it, otherwise it throws.

metaMask.unlock(password: string): Promise<void>

it unlocks the MetaMask extension. It can only be used in you locked/signed out before, otherwise it throws. The password is optional, it defaults to password1234.

metaMask.switchNetwork(network: string): Promise<void>

it changes the current selected network. networkName can take the following values: "mainnet", "goerli", "sepolia", "ropsten", "rinkeby", "kovan", "localhost".

metaMask.acceptAddNetwork(shouldSwitch?: boolean): Promise<void>

commands MetaMask to accept a Network addition. For this to work MetaMask has to be in a Network addition state (basically prompting the user to accept/reject a Network addition). You can optionally tell MetaMask to switch to this network by passing the true parameter (default to false).

metaMask.rejectAddNetwork(): Promise<void>

commands MetaMask to reject a Network addition. For this to work MetaMask has to be in a Network addition state (basically prompting the user to accept/reject a Network addition).

metaMask.acceptAddToken(): Promise<void>

commands MetaMask to accept a Token addition. For this to work MetaMask has to be in a Token addition state (basically prompting the user to accept/reject a Token addition).

metaMask.rejectAddToken(): Promise<void>

commands MetaMask to reject a Token addition. For this to work MetaMask has to be in a Token addition state (basically prompting the user to accept/reject a Token addition).

metaMask.confirmTransaction(options?: TransactionOptions): Promise<void>

interface TransactionOptions {
  gas?: number;
  gasLimit?: number;
  priority?: number;
}

commands MetaMask to submit a transaction. For this to work MetaMask has to be in a transaction confirmation state (basically prompting the user to submit/reject a transaction). You can (optionally) pass an object with gas and/or gasLimit, by default they are 20 and 50000 respectively.

metaMask.sign(): Promise<void>

commands MetaMask to sign a message. For this to work MetaMask must be in a sign confirmation state.

metaMask.signTypedData(): Promise<void>

commands MetaMask to sign a message. For this to work MetaMask must be in a sign typed data confirmation state.

metaMask.approve(): Promise<void>

enables the app to connect to MetaMask account in privacy mode

Helpers methods

metaMask.helpers.getTokenBalance(tokenSymbol: string): Promise<number>

get balance of specific token

metaMask.helpers.deleteAccount(accountNumber: number): Promise<void>

deletes account containing name with specified number

metaMask.helpers.deleteNetwork(): Promise<void>

deletes custom network from metaMask

metaMask.page is the MetaMask plugin Page

for advanced usages in case you need custom features.

Snaps methods

metaMask.snaps.installSnap: (snapIdOrLocation: string, opts?: { customSteps?: InstallStep[]; version?: string;},installationSnapUrl?: string) => Promise;

installs the snap. The snapIdOrLocation param is either the snapId or the full path to your snap directory.

metaMask.snaps.invokeSnap<Result = unknown, Params extends Serializable = Serializable>(page: DappeteerPage,snapId: string,method: string,params?: Params): Promise<Partial<Result>>

invokes a MetaMask snap method. The snapId is the id of your installed snap (result of invoking installSnap method). This function will throw if there is an error while invoking snap.

metaMask.snaps.getNotificationEmitter(): Promise<NotificationsEmitter>

returns emitter to listen for notifications appearance in notification page

metaMask.snaps.getAllNotifications(): Promise<NotificationList>

Returns all notifications in MetaMask notifications page

metaMask.snaps.dialog.accept(): Promise<void>

accepts a snap_dialog dialog

metaMask.snaps.dialog.reject(): Promise<void>

rejects snap_dialog dialog

metaMask.snaps.dialog.type(value: string): Promise<void>

type value in snap_dialog dialog