playwright-web3

Playwright-Web3 Library

Note: This package is currently in its conceptual phase and is not recommended for production use yet. Until v1 you will see many breaking changes.

Updates: adding metamask, solflare and trust

Overview

The playwright-web3 library provides a straightforward solution for interacting with web3 wallet extensions, handling core functionalities such as importing wallets and signing requests with minimal effort. This library simplifies the process of downloading or extracting wallet .crx extensions and supplies the Page objects needed to interact with them.

Installation

Install the library using npm:

npm install --save-dev playwright-web3

Features

• Download or Extract Extensions: Automatically handle the .crx files either by downloading them from the Chrome Store or using a local copy.

• Easy Interaction: Provides out-of-the-box methods to interact with wallet functionalities like importing wallets and signing transactions.

Usage

Preparing the Extension

Use the prepareExtension function to set up the wallet extension. This function can either fetch the latest version from the Chrome Web Store, or the stable version ( more likely to be working with the page object of this library), that will fetch the crx from: https://github.com/PabloZimmermann/crx. However, you can also use a specified local path.

const extensionPath = await prepareExtension("phantom", "your-project/crx/Phantom 24.5.0.0.crx") //replace path with your own

Configuring Playwright Test Environment

To integrate playwright-web3 with Playwright's testing framework, modify the test setup as follows:

Create a Setup File: Define your browser context and extend the Playwright test functionalities in a setup file.

// your-project/setup.ts

import { test as base, chromium, BrowserContext } from "@playwright/test"
import { Phantom, prepareExtension } from "playwright-web3"

let browserContext: BrowserContext | null = null

export const test = base.extend<{ context: BrowserContext }>({
    context: async ({}, use) => {
        await use(browserContext!)
    }
})

export const expect = test.expect

test.beforeAll(async () => {
    const extensionPath = await prepareExtension("phantom", "utils/crx/Phantom 24.5.0.0.crx")

    browserContext = await chromium.launchPersistentContext("", {
        headless: false,
        args: [
            `--disable-extensions-except=${extensionPath}`,
             `--load-extension=${extensionPath}`,
            `--headless=new`, // To run in headless mode with extensions. Playwright official documentation says that this flag could cause unexpected issues, but it is working fine for me.
            ]
    })

    // if you need to open the wallet in a new tab to add some settings you will have to store the extensionId:
   let [background] = context.backgroundPages() // backgroundPages() will work only with manifest v2, if you extension is v3 you will use context.serviceWorkers()
    if (!background)
         background = await context.waitForEvent('backgroundpage') // for v3 extensions use context.waitForEvent('serviceworker');
    const timeout = 2000;
    const extensionId = background.url().split('/')[2];
    const phantom = new Phantom(context, timeout, extensionId)
    await phantom.importWallet(secretWords)
    await browserContext.phantom = phantom // store the extension in the context to have access on tests
})

Global Module Augmentation: To reuse the Phantom object across different tests without re-instantiation, augment the BrowserContext type.

// your-project/test/global.d.ts

import { Phantom } from "playwright-web3"

declare module "@playwright/test" {
    interface BrowserContext {
        phantom: Phantom
    }
}

Writing Tests

Import the extended test configuration from your setup file and utilize the phantom object directly from the browser context.

import { test } from "/your-project/setup"

test.describe.only("Deposits", () => {
    test.beforeAll(async ({ context }) => {
        // Use phantom methods here if needed
        await context.phantom
    })

    test("make deposit", async ({ context }) => {
        // Use phantom methods here if needed
        await context.phantom
    })
})