{"_id":"@0xbigboss/headless-web3-provider","_rev":"3-1982f602c3ef407a1fe0a0575b2de42c","name":"@0xbigboss/headless-web3-provider","dist-tags":{"latest":"0.2.6"},"versions":{"0.2.5":{"name":"@0xbigboss/headless-web3-provider","version":"0.2.5","license":"MIT","_id":"@0xbigboss/headless-web3-provider@0.2.5","homepage":"https://github.com/0xbigboss/headless-web3-provider#readme","bugs":{"url":"https://github.com/0xbigboss/headless-web3-provider/issues"},"dist":{"shasum":"dc098b0b793a71074f6a96c968ba8a81f2e1bfbe","tarball":"https://registry.npmjs.org/@0xbigboss/headless-web3-provider/-/headless-web3-provider-0.2.5.tgz","fileCount":10,"integrity":"sha512-FUoFODruV1nhQru+ZK1e++ZpkjOhUHJJCBHbuZvycVuUscEC91c6WhUDrrf0j0QB9djloRkkp0531r9Ch4/cbQ==","signatures":[{"sig":"MEYCIQD7eqLtcb1GpUH6erK1DBqsWyI7uebsfDvBNamLkm5jRAIhAPPhgHibN96WwSMpCZA3CCQgVMNeNVqsKA7hJcKbWVRD","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":180111},"main":"dist/main.cjs","types":"dist/types.d.ts","module":"dist/module.mjs","source":"src/index.ts","authors":["Big Boss <bigboss@metalrodeo.xyz>","Emil Ibatullin"],"scripts":{"test":"playwright test","build":"parcel build --no-optimize","watch":"parcel watch","prettify":"prettier --write '**/*.ts'"},"_npmUser":{"name":"0xbigboss","email":"0xbigboss@proton.me"},"repository":{"url":"git+https://github.com/0xbigboss/headless-web3-provider.git","type":"git"},"description":"Headless Web3 Provider useful in e2e testing","directories":{},"sideEffects":false,"dependencies":{"rxjs":"^7.5.7","ethers":"^5.7.1","@metamask/eth-sig-util":"^6.0.0","@metamask/json-rpc-engine":"^8.0.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^3.12.10","parcel":"^2.7.0","prettier":"^2.7.1","typescript":"~4.7.0","@types/node":"^16.0.0","generic-pool":"^3.9.0","@playwright/test":"^1.26.1","@parcel/packager-ts":"2.7.0","@parcel/transformer-typescript-types":"^2.7.0"},"_npmOperationalInternal":{"tmp":"tmp/headless-web3-provider_0.2.5_1719016778311_0.2905634020613781","host":"s3://npm-registry-packages"}},"0.2.6":{"name":"@0xbigboss/headless-web3-provider","version":"0.2.6","license":"MIT","_id":"@0xbigboss/headless-web3-provider@0.2.6","maintainers":[{"name":"0xbigboss","email":"0xbigboss@proton.me"}],"homepage":"https://github.com/0xbigboss/headless-web3-provider#readme","bugs":{"url":"https://github.com/0xbigboss/headless-web3-provider/issues"},"dist":{"shasum":"74738447feecb87d9c5ec729b06024bcc113bf73","tarball":"https://registry.npmjs.org/@0xbigboss/headless-web3-provider/-/headless-web3-provider-0.2.6.tgz","fileCount":10,"integrity":"sha512-kkWlhJZcmjnX9PVB4wf8/itTb2Fwxu1duIcWjoytRJB597fm9Mmnmowg5cBaMzd3u4gMxqdU1XlNPyWcLVeK8w==","signatures":[{"sig":"MEUCIGSAwauToBB8kCGArOvL/mvqCasUFGws0GHs/NBMvbGHAiEAiin/1Gd7ZtA30xR2U3Gxggm6zjY/cvDrRYRY3XcJk0M=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":180368},"main":"dist/main.cjs","types":"dist/types.d.ts","module":"dist/module.mjs","source":"src/index.ts","authors":["Big Boss <bigboss@metalrodeo.xyz>","Emil Ibatullin"],"scripts":{"test":"playwright test","build":"parcel build --no-optimize","watch":"parcel watch","prettify":"prettier --write '**/*.ts'"},"_npmUser":{"name":"0xbigboss","email":"0xbigboss@proton.me"},"repository":{"url":"git+https://github.com/0xbigboss/headless-web3-provider.git","type":"git"},"description":"Headless Web3 Provider useful in e2e testing","directories":{},"sideEffects":false,"dependencies":{"rxjs":"^7.5.7","ethers":"^5.7.1","@metamask/eth-sig-util":"^6.0.0","@metamask/json-rpc-engine":"^8.0.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^3.12.10","parcel":"^2.7.0","prettier":"^2.7.1","typescript":"~4.7.0","@types/node":"^16.0.0","generic-pool":"^3.9.0","@playwright/test":"^1.26.1","@parcel/packager-ts":"2.7.0","@parcel/transformer-typescript-types":"^2.7.0"},"_npmOperationalInternal":{"tmp":"tmp/headless-web3-provider_0.2.6_1721587864736_0.6365776813470181","host":"s3://npm-registry-packages"}}},"time":{"created":"2024-06-22T00:39:38.217Z","modified":"2026-06-24T17:39:10.826Z","0.2.5":"2024-06-22T00:39:38.477Z","0.2.6":"2024-07-21T18:51:04.929Z"},"bugs":{"url":"https://github.com/0xbigboss/headless-web3-provider/issues"},"license":"MIT","homepage":"https://github.com/0xbigboss/headless-web3-provider#readme","repository":{"url":"git+https://github.com/0xbigboss/headless-web3-provider.git","type":"git"},"description":"Headless Web3 Provider useful in e2e testing","maintainers":[{"email":"0xbigboss@proton.me","name":"alleneubank"}],"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) => {\n    await use((page, privateKeys = signers) =>\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 }) => {\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(() => Wallet.createRandom()) as [Wallet, Wallet]\n\n  // Create an instance of the Web3ProviderBackend class\n  let web3Manager: Web3ProviderBackend = makeHeadlessWeb3Provider(\n    wallets.map((wallet) => 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('<AccountConnect />', () => {\n  let wallets: [Wallet, ...Wallet[]]\n  let web3Manager: Web3ProviderBackend\n\n  beforeEach(() => {\n    // Inject window.ethereum instance\n    ;[wallets, web3Manager] = injectWeb3Provider()\n  })\n\n  it('renders user address after connecting', async () => {\n    render(<AccountConnect />)\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 () => {\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","readmeFilename":"README.md"}