{"id":17336,"library":"prool","title":"Prool","description":"Prool is a TypeScript-first library designed to provide programmatic HTTP testing instances for various Ethereum components. It enables developers to spin up local execution nodes (like Anvil and Tempo) and ERC-4337 bundler nodes (like Alto) within testing environments such as Vitest. The library is currently at version `0.2.4` and maintains an active release cadence with frequent patch and minor updates. A key differentiator is its focus on streamlining the setup and teardown of these instances for reliable, isolated tests, abstracting away the complexities of managing external processes or Docker containers. Users can utilize pre-configured instances or define custom ones to suit specific testing needs, requiring Node.js >=22. It integrates with `testcontainers` for containerized instances.","status":"active","version":"0.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/wevm/prool","tags":["javascript","typescript"],"install":[{"cmd":"npm install prool","lang":"bash","label":"npm"},{"cmd":"yarn add prool","lang":"bash","label":"yarn"},{"cmd":"pnpm add prool","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for using the `Instance.alto` bundler node instance.","package":"@pimlico/alto","optional":true},{"reason":"Peer dependency used internally for managing Docker containers for instances like Tempo. Must be installed separately.","package":"testcontainers","optional":false}],"imports":[{"note":"Prool is an ESM-first library; CommonJS `require` will lead to errors in Node.js environments. Use `import` statements.","wrong":"const { Server } = require('prool')","symbol":"Server","correct":"import { Server } from 'prool'"},{"note":"The main `Instance` object for common instances like Anvil and Alto. For Tempo (containerized), see the `prool/testcontainers` entrypoint.","wrong":"const { Instance } = require('prool')","symbol":"Instance","correct":"import { Instance } from 'prool'"},{"note":"Since `v0.2.0`, containerized instances like Tempo were moved to the `prool/testcontainers` entrypoint and `tempoDocker` was renamed to `tempo`.","wrong":"import { Instance } from 'prool'; Instance.tempoDocker","symbol":"Instance.tempo","correct":"import { Instance } from 'prool/testcontainers'"}],"quickstart":{"code":"import { Instance, Server } from 'prool';\n\n// NOTE: Requires Foundry to be installed globally:\n// `curl -L https://foundry.paradigm.xyz | bash`\n\nasync function runAnvilServer() {\n  const server = Server.create({\n    instance: Instance.anvil(),\n    port: 8545 // Optional, default is 8545\n  });\n\n  try {\n    console.log('Starting Anvil server...');\n    await server.start();\n    console.log('Anvil server started successfully!');\n    console.log('Instances accessible at:');\n    // Access the base URL for instances, e.g., for direct RPC calls\n    // `server.url` returns 'http://localhost:8545/'\n    // The specific instances are accessed via paths, e.g., 'http://localhost:8545/1'\n    console.log(`  Base URL: ${server.url}`);\n    console.log('  Example instance URL: http://localhost:8545/1');\n\n    // Simulate some work or keep it running for a test suite\n    await new Promise(resolve => setTimeout(resolve, 5000)); // Keep alive for 5 seconds\n\n  } catch (error) {\n    console.error('Failed to start Anvil server:', error);\n  } finally {\n    console.log('Stopping Anvil server...');\n    await server.stop();\n    console.log('Anvil server stopped.');\n  }\n}\n\nrunAnvilServer();","lang":"typescript","description":"Demonstrates how to create and manage an Anvil execution node instance using Prool, including starting and stopping the server, and noting required external dependencies."},"warnings":[{"fix":"Change your import from `import { Instance } from 'prool'` to `import { Instance } from 'prool/testcontainers'` and update `Instance.tempoDocker` to `Instance.tempo`.","message":"The `Instance.tempoDocker` property was removed and its functionality was moved to a new entrypoint `prool/testcontainers`. The method itself was renamed to `Instance.tempo`.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"If you were using these instances, you will need to migrate to alternative solutions or define a custom instance using `Instance.define` if the underlying service is still supported elsewhere.","message":"Several pre-configured instances, specifically `silius`, `stackup`, and `rundler`, were removed from the library.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure your Node.js environment is updated to version 22 or later. You can use a version manager like `nvm` to switch Node.js versions: `nvm install 22 && nvm use 22`.","message":"Prool requires Node.js version 22 or higher due to its use of modern JavaScript features and ESM-first design.","severity":"gotcha","affected_versions":"<=0.2.4"},{"fix":"Upgrade Prool to `v0.2.4` or newer. This version fixes the issue by ensuring containers bind to `127.0.0.1` with dynamically mapped exposed ports.","message":"For containerized instances (e.g., Tempo via `prool/testcontainers`), macOS users might experience connectivity issues if running versions older than `v0.2.4` due to host networking configurations. Prior versions might not correctly bind to `127.0.0.1`.","severity":"gotcha","affected_versions":"<0.2.4"},{"fix":"Install Foundry (for Anvil) via `curl -L https://foundry.paradigm.xyz | bash` or Tempo CLI (for Tempo) via `curl -L https://tempo.xyz/install | bash`.","message":"Using instances like `Instance.anvil()` or `Instance.tempo()` requires the respective CLI tools (Foundry or Tempo CLI) to be installed globally on your system, or accessible in your PATH.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update your import statement to `import { Instance } from 'prool/testcontainers'` and change `Instance.tempoDocker` to `Instance.tempo`.","cause":"After upgrading to `prool` v0.2.0 or later, the `tempoDocker` instance was moved and renamed.","error":"TypeError: Instance.tempoDocker is not a function"},{"fix":"Switch to ESM `import` statements: `import { Server } from 'prool'` instead of `const { Server } = require('prool')`.","cause":"Attempting to use CommonJS `require()` syntax with Prool, which is an ESM-first library requiring Node.js >=22.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead, change the require of index.js in ... to a dynamic import() call."},{"fix":"Upgrade Prool to `v0.2.4` or newer to leverage the fix for macOS host networking. Ensure Docker Desktop is running and healthy.","cause":"On macOS, prior to `v0.2.4`, containerized instances like Tempo might have issues with port binding and host networking, leading to connection refusals.","error":"Error: Tempo container failed to start: Error: connect ECONNREFUSED 127.0.0.1:XXXX"},{"fix":"Install Foundry globally by running `curl -L https://foundry.paradigm.xyz | bash` and ensure it's added to your shell's PATH.","cause":"The `Instance.anvil()` relies on the `anvil` executable from Foundry, which is not found in the system's PATH.","error":"Error: Command failed with exit code 1: foundryup"}],"ecosystem":"npm","meta_description":null}