{"id":22861569,"url":"https://github.com/epappas/anvil-testcontainer","last_synced_at":"2026-03-04T21:34:09.056Z","repository":{"id":267872921,"uuid":"902618771","full_name":"epappas/anvil-testcontainer","owner":"epappas","description":"A Python library for managing Anvil Ethereum test containers, pythonic \u0026 natively. Just `pip install anvil-testcontainer`","archived":false,"fork":false,"pushed_at":"2025-05-19T21:21:48.000Z","size":451,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-24T00:46:29.538Z","etag":null,"topics":["anvil","docker","ethereum","foundry","python","testcontainers","testing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/anvil-testcontainer","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epappas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-12T23:35:21.000Z","updated_at":"2025-06-26T12:11:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"92d065ec-953f-43d5-817d-0c0b5b07e16a","html_url":"https://github.com/epappas/anvil-testcontainer","commit_stats":null,"previous_names":["epappas/anvil-testcontainer"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/epappas/anvil-testcontainer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epappas%2Fanvil-testcontainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epappas%2Fanvil-testcontainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epappas%2Fanvil-testcontainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epappas%2Fanvil-testcontainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epappas","download_url":"https://codeload.github.com/epappas/anvil-testcontainer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epappas%2Fanvil-testcontainer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30093975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T20:42:30.420Z","status":"ssl_error","status_checked_at":"2026-03-04T20:42:30.057Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["anvil","docker","ethereum","foundry","python","testcontainers","testing"],"created_at":"2024-12-13T10:09:35.636Z","updated_at":"2026-03-04T21:34:09.040Z","avatar_url":"https://github.com/epappas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Anvil Test Container\n\nA Python library for managing Anvil Ethereum test containers with security and ease of use in mind. This library provides a clean interface for running and interacting with Anvil instances in Docker containers, making it perfect for testing Ethereum smart contracts and DApps.\n\n## Features\n\nThis library offers several key features for Ethereum development and testing:\n\n### Core Functionality\n\n- Automated container lifecycle management\n- Ethereum chain forking and manipulation\n- Secure command execution\n- Transaction handling\n- Block time control\n\n### Advanced Features\n\n- Chain state snapshots and restoration\n- Health monitoring and diagnostics\n- Container log access\n- Resource cleanup and management\n- Environment variable handling\n\n### Security\n\n- Input validation for Ethereum addresses\n- Command injection protection\n- Secure transaction handling\n- Safe environment variable management\n- Resource isolation\n\n## Installation\n\nYou can install the library using pip:\n\n```bash\npip install anvil-testcontainer\n```\n\nOr with Poetry (recommended):\n\n```bash\npoetry add anvil-testcontainer\n```\n\n### Prerequisites\n\n- Python 3.8 or higher\n- Docker installed and running\n- Access to an Ethereum node for forking (e.g., Infura, Alchemy)\n\n## Quick Start\n\nHere's a simple example to get you started:\n\n```python\nfrom anvil_testcontainer import AnvilContainer\n\nwith AnvilContainer(\"\u003crpc provider url eg https://eth-mainnet.alchemyapi.io/v2..\u003e\") as anvil:\n    web3 = anvil.get_web3()\n    \n    print(f\"Current block: {web3.eth.block_number}\")\n    \n    anvil.move_time(86400)\n```\n\n## Advanced Usage\n\n### Configuration\n\nUse the `ContainerConfig` class for more control:\n\n```python\nfrom anvil_testcontainer import AnvilContainer, ContainerConfig\n\nconfig = ContainerConfig(\n    fork_url=\"\u003cprovider URL\u003e\",\n    fork_block_number=14000000,\n    image=\"ghcr.io/foundry-rs/foundry:nightly\",\n    port=8545,\n    timeout=60,\n    env_vars={\"ETHERSCAN_API_KEY\": \"your-key\"}\n)\n\nwith AnvilContainer(config) as anvil:\n    snapshot_id = anvil.create_snapshot()\n\n    tx_hash = anvil.send_transaction(\n        from_address=\"0x742d35Cc6634C0532925a3b844Bc454e4438f44e\",\n        to_address=\"0x742d35Cc6634C0532925a3b844Bc454e4438f44e\",\n        value=100000000000000000  # 0.1 ETH\n    )\n\n    receipt = anvil.get_web3().eth.wait_for_transaction_receipt(tx_hash)\n\n    anvil.revert_snapshot(snapshot_id)\n```\n\n### Health Monitoring\n\nMonitor container health and access logs:\n\n```python\nwith AnvilContainer(config) as anvil:\n    # Check container health\n    if anvil.verify_health():\n        print(\"Container is healthy\")\n    \n    # Access container logs\n    logs = anvil.get_logs()\n    print(logs)\n```\n\n## API Reference\n\n### AnvilContainer\n\nThe main class for container management.\n\n#### Basic Methods\n\n- `start()`: Start the container\n- `stop()`: Stop the container\n- `get_web3()`: Get Web3 instance\n- `move_time(seconds: int)`: Advance blockchain time\n- `reset_fork(block_number: int)`: Reset to specific block\n\n#### Advanced Methods\n\n- `create_snapshot()`: Create chain state snapshot\n- `revert_snapshot(snapshot_id: str)`: Restore chain state\n- `send_transaction(...)`: Execute transaction\n- `verify_health()`: Check container health\n- `get_logs()`: Retrieve container logs\n\n### ContainerConfig\n\nConfiguration class for container initialization.\n\n```python\nContainerConfig(\n    fork_url: str,\n    fork_block_number: Optional[int] = None,\n    image: str = \"ghcr.io/foundry-rs/foundry:nightly\",\n    port: int = 8545,\n    timeout: int = 60,\n    env_vars: Optional[Dict[str, str]] = None\n)\n```\n\n## Error Handling\n\nThe library provides custom exceptions for better error handling:\n\n```python\nfrom anvil_testcontainer import ValidationError\n\ntry:\n    with AnvilContainer(config) as anvil:\n        anvil.send_transaction(\n            from_address=\"invalid_address\",\n            to_address=\"0x742d35Cc6634C0532925a3b844Bc454e4438f44e\",\n            value=1000000000000000000\n        )\nexcept ValidationError as e:\n    print(f\"Validation failed: {e}\")\n```\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add or update tests\n5. Submit a pull request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/epappas/anvil-testcontainer.git\ncd anvil-testcontainer\n\npoetry install\n\npoetry run pytest\n```\n\n### Testing\n\nRun the test suite:\n\n```bash\npoetry run pytest\n```\n\nWith coverage:\n\n```bash\npoetry run pytest --cov=anvil_testcontainer\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor support, please:\n\n1. Check the documentation\n2. Search existing issues\n3. Create a new issue if needed\n\n## Acknowledgments\n\n- Foundry team for Anvil\n- OpenZeppelin for security best practices\n- Web3.py team for Ethereum interaction capabilities\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepappas%2Fanvil-testcontainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepappas%2Fanvil-testcontainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepappas%2Fanvil-testcontainer/lists"}