{"id":22261221,"url":"https://github.com/cawabunga/headless-web3-provider","last_synced_at":"2025-04-05T05:08:57.840Z","repository":{"id":63756260,"uuid":"544531306","full_name":"cawabunga/headless-web3-provider","owner":"cawabunga","description":"Web3 wallet emulation similar to Metamask for testing Ethereum-based apps","archived":false,"fork":false,"pushed_at":"2024-12-02T10:46:21.000Z","size":114,"stargazers_count":51,"open_issues_count":1,"forks_count":13,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T04:11:34.227Z","etag":null,"topics":["ethereum","metamask","playwright","web3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cawabunga.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-02T17:59:23.000Z","updated_at":"2024-12-02T10:46:17.000Z","dependencies_parsed_at":"2024-06-19T11:27:29.736Z","dependency_job_id":"c4c00e07-4ac3-484a-afa7-507c4f8fec99","html_url":"https://github.com/cawabunga/headless-web3-provider","commit_stats":{"total_commits":48,"total_committers":3,"mean_commits":16.0,"dds":0.25,"last_synced_commit":"dcd876e4d2068f839ef229ae3543e52ee511edfe"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawabunga%2Fheadless-web3-provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawabunga%2Fheadless-web3-provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawabunga%2Fheadless-web3-provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawabunga%2Fheadless-web3-provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cawabunga","download_url":"https://codeload.github.com/cawabunga/headless-web3-provider/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289429,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum","metamask","playwright","web3"],"created_at":"2024-12-03T09:11:55.227Z","updated_at":"2025-04-05T05:08:57.825Z","avatar_url":"https://github.com/cawabunga.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Headless Web3 Provider\n\n[![Playwright Tests](https://github.com/cawabunga/headless-web3-provider/actions/workflows/playwright.yml/badge.svg)](https://github.com/cawabunga/headless-web3-provider/actions/workflows/playwright.yml) ![NPM Downloads](https://img.shields.io/npm/dw/headless-web3-provider)\n\nUpgrade your E2E tests with `headless-web3-provider` - the Metamask replacement for Ethereum-based apps. No visual interface needed, control transactions directly from your code!\n\n## Installation\n\n```shell\nnpm i -D headless-web3-provider\n```\n\n## About\n\nThe `headless-web3-provider` library emulates a Web3 wallet similar to Metamask and provides programmatic control over various operations, such as switching networks, connecting a wallet, and sending transactions, making it useful for end-to-end testing of Ethereum-based applications. It allows to programmatically accept or decline operations, making it handy for test automation.\n\n#### Supported methods\n\n| Method                     | Confirmable |\n| -------------------------- | ----------- |\n| eth_requestAccounts        | Yes         |\n| eth_accounts               | Yes         |\n| eth_sendTransaction        | Yes         |\n| wallet_addEthereumChain    | Yes         |\n| wallet_switchEthereumChain | Yes         |\n| wallet_requestPermissions  | Yes         |\n| personal_sign              | Yes         |\n| eth_signTypedData          | Yes         |\n| eth_signTypedData_v1       | Yes         |\n| eth_signTypedData_v3       | Yes         |\n| eth_signTypedData_v4       | Yes         |\n| eth_call                   | No          |\n| eth_estimateGas            | No          |\n| eth_blockNumber            | No          |\n| eth_getBlockByNumber       | No          |\n| eth_getTransactionByHash   | No          |\n| eth_getTransactionReceipt  | No          |\n| eth_chainId                | No          |\n| net_version                | No          |\n\n## Examples\n\n### Playwright\n\nBelow given a simple example. More complex scenarios you can find in [tests/e2e](./tests/e2e) folder.\n\nSetup (add a fixture):\n\n```js\n// tests/fixtures.js\nimport { test as base } from '@playwright/test'\nimport { injectHeadlessWeb3Provider } from 'headless-web3-provider'\n\nexport const test = base.extend({\n  // signers - the private keys that are to be used in the tests\n  signers: [process.env.PRIVATE_KEY],\n\n  // injectWeb3Provider - function that injects web3 provider instance into the page\n  injectWeb3Provider: async ({ signers }, use) =\u003e {\n    await use((page, privateKeys = signers) =\u003e\n      injectHeadlessWeb3Provider(\n        page,\n        privateKeys, // Private keys that you want to use in tests\n        31337, // Chain ID - 31337 is common testnet id\n        'http://localhost:8545' // Ethereum client's JSON-RPC URL\n      )\n    )\n  },\n})\n```\n\nUsage:\n\n```js\n// tests/e2e/example.spec.js\nimport { test } from '../fixtures'\n\ntest('connect the wallet', async ({ page, injectWeb3Provider }) =\u003e {\n  // Inject window.ethereum instance\n  const wallet = await injectWeb3Provider(page)\n\n  await page.goto('https://metamask.github.io/test-dapp/')\n\n  // Request connecting the wallet\n  await page.getByRole('button', { name: 'Connect', exact: true }).click()\n\n  // You can either authorize or reject the request\n  await wallet.authorize(Web3RequestKind.RequestAccounts)\n\n  // Verify if the wallet is really connected\n  await test.expect(page.locator('text=Connected')).toBeVisible()\n  await test\n    .expect(page.locator('text=0x8b3a08b22d25c60e4b2bfd984e331568eca4c299'))\n    .toBeVisible()\n})\n```\n\n### Jest\n\nAdd a helper script for injecting the ethereum provider instance.\n\n```ts\n// tests/web3-helper.ts\nimport { Wallet } from 'ethers'\nimport {\n  makeHeadlessWeb3Provider,\n  Web3ProviderBackend,\n} from 'headless-web3-provider'\n\n/**\n * injectWeb3Provider - Function to create and inject web3 provider instance into the global window object\n *\n * @returns {Array} An array containing the wallets and the web3Provider instance\n */\nexport function injectWeb3Provider(): [\n  [Wallet, ...Wallet[]],\n  Web3ProviderBackend\n] {\n  // Create 2 random instances of Wallet class\n  const wallets = Array(2)\n    .fill(0)\n    .map(() =\u003e Wallet.createRandom()) as [Wallet, Wallet]\n\n  // Create an instance of the Web3ProviderBackend class\n  let web3Manager: Web3ProviderBackend = makeHeadlessWeb3Provider(\n    wallets.map((wallet) =\u003e wallet.privateKey),\n    31337, // Chain ID - 31337 or  is a common testnet id\n    'http://localhost:8545' // Ethereum client's JSON-RPC URL\n  )\n\n  // Expose the web3Provider instance to the global window object\n  // @ts-ignore-error\n  window.ethereum = web3Manager\n\n  // Return the created wallets and web3Provider instance\n  return [wallets, web3Manager]\n}\n```\n\n```ts\n// AccountConnect.test.ts\nimport { act, render, screen } from '@testing-library/react'\nimport type { Wallet } from 'ethers'\nimport { Web3ProviderBackend, Web3RequestKind } from 'headless-web3-provider'\nimport userEvent from '@testing-library/user-event'\nimport { injectWeb3Provider } from 'tests/web3-helper' // Our just created helper script\nimport AccountConnect from './AccountConnect'\n\ndescribe('\u003cAccountConnect /\u003e', () =\u003e {\n  let wallets: [Wallet, ...Wallet[]]\n  let web3Manager: Web3ProviderBackend\n\n  beforeEach(() =\u003e {\n    // Inject window.ethereum instance\n    ;[wallets, web3Manager] = injectWeb3Provider()\n  })\n\n  it('renders user address after connecting', async () =\u003e {\n    render(\u003cAccountConnect /\u003e)\n\n    // Request connecting the wallet\n    await userEvent.click(\n      screen.getByRole('button', { name: /connect wallet/i })\n    )\n\n    // Verify if the wallet is NOT yet connected\n    expect(screen.queryByText(wallets[0].address)).not.toBeInTheDocument()\n\n    await act(async () =\u003e {\n      // You can either authorize or reject the request\n      await web3Manager.authorize(Web3RequestKind.RequestAccounts)\n    })\n\n    // Verify if the wallet is connected\n    expect(screen.getByText(wallets[0].address)).toBeInTheDocument()\n  })\n})\n```\n\n## Additional Tools\n\nEnhance your testing environment with these complementary tools that integrate seamlessly with `headless-web3-provider`:\n\n- [Foundry Anvil](https://book.getfoundry.sh/anvil/) - a dev chain platform ideal for testing your applications against.\n\n## Resources\n\n- [Metamask Test DApp](https://metamask.github.io/test-dapp/)\n- [Metamask JSON-RPC API](https://metamask.github.io/api-playground/api-documentation/)\n- [Metamask Provider API](https://docs.metamask.io/guide/ethereum-provider.html)\n- [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) Ethereum Provider JavaScript API\n- [EIP-3085](https://eips.ethereum.org/EIPS/eip-3085) Wallet Add Ethereum Chain RPC Method (`wallet_addEthereumChain`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcawabunga%2Fheadless-web3-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcawabunga%2Fheadless-web3-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcawabunga%2Fheadless-web3-provider/lists"}