Registry / testing / prool
library0.2.4jsnpmunverified

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.

npm install prool
INSTALL
IMPORT
SIG · PROOL
P
prool
testingjavascriptv0.2.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server
import { Server } from 'prool'
const { Server } = require('prool')
Prool is an ESM-first library; CommonJS `require` will lead to errors in Node.js environments. Use `import` statements.
Instance
import { Instance } from 'prool'
const { Instance } = require('prool')
The main `Instance` object for common instances like Anvil and Alto. For Tempo (containerized), see the `prool/testcontainers` entrypoint.
Instance.tempo
import { Instance } from 'prool/testcontainers'
import { Instance } from 'prool'; Instance.tempoDocker
Since `v0.2.0`, containerized instances like Tempo were moved to the `prool/testcontainers` entrypoint and `tempoDocker` was renamed to `tempo`.

Demonstrates how to create and manage an Anvil execution node instance using Prool, including starting and stopping the server, and noting required external dependencies.

import { Instance, Server } from 'prool'; // NOTE: Requires Foundry to be installed globally: // `curl -L https://foundry.paradigm.xyz | bash` async function runAnvilServer() { const server = Server.create({ instance: Instance.anvil(), port: 8545 // Optional, default is 8545 }); try { console.log('Starting Anvil server...'); await server.start(); console.log('Anvil server started successfully!'); console.log('Instances accessible at:'); // Access the base URL for instances, e.g., for direct RPC calls // `server.url` returns 'http://localhost:8545/' // The specific instances are accessed via paths, e.g., 'http://localhost:8545/1' console.log(` Base URL: ${server.url}`); console.log(' Example instance URL: http://localhost:8545/1'); // Simulate some work or keep it running for a test suite await new Promise(resolve => setTimeout(resolve, 5000)); // Keep alive for 5 seconds } catch (error) { console.error('Failed to start Anvil server:', error); } finally { console.log('Stopping Anvil server...'); await server.stop(); console.log('Anvil server stopped.'); } } runAnvilServer();
Debug
Known issues
breakingThe `Instance.tempoDocker` property was removed and its functionality was moved to a new entrypoint `prool/testcontainers`. The method itself was renamed to `Instance.tempo`.
fix
Change your import from `import { Instance } from 'prool'` to `import { Instance } from 'prool/testcontainers'` and update `Instance.tempoDocker` to `Instance.tempo`.
affects: >=0.2.0
breakingSeveral pre-configured instances, specifically `silius`, `stackup`, and `rundler`, were removed from the library.
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.
affects: >=0.1.0
gotchaProol requires Node.js version 22 or higher due to its use of modern JavaScript features and ESM-first design.
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`.
affects: <=0.2.4
gotchaFor 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`.
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.
affects: <0.2.4
gotchaUsing 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.
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`.
affects: >=0.0.0
Errors
Common errors & fixes
TypeError: Instance.tempoDocker is not a function
After upgrading to `prool` v0.2.0 or later, the `tempoDocker` instance was moved and renamed.
fix
Update your import statement to `import { Instance } from 'prool/testcontainers'` and change `Instance.tempoDocker` to `Instance.tempo`.
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead, change the require of index.js in ... to a dynamic import() call.
Attempting to use CommonJS `require()` syntax with Prool, which is an ESM-first library requiring Node.js >=22.
fix
Switch to ESM `import` statements: `import { Server } from 'prool'` instead of `const { Server } = require('prool')`.
Error: Tempo container failed to start: Error: connect ECONNREFUSED 127.0.0.1:XXXX
On macOS, prior to `v0.2.4`, containerized instances like Tempo might have issues with port binding and host networking, leading to connection refusals.
fix
Upgrade Prool to `v0.2.4` or newer to leverage the fix for macOS host networking. Ensure Docker Desktop is running and healthy.
Error: Command failed with exit code 1: foundryup
The `Instance.anvil()` relies on the `anvil` executable from Foundry, which is not found in the system's PATH.
fix
Install Foundry globally by running `curl -L https://foundry.paradigm.xyz | bash` and ensure it's added to your shell's PATH.
Upgrade
Version history
0.2.4latest on npm
Audit
Dependencies
@pimlico/altooptionalRequired for using the `Instance.alto` bundler node instance.
testcontainersrequiredPeer dependency used internally for managing Docker containers for instances like Tempo. Must be installed separately.
Agent activity
9 hits · last 30 days
node
8
Resources
prool — npm install prool · libregistry