{"id":28495599,"url":"https://github.com/lfdt-web3j/web3j-unit","last_synced_at":"2026-01-19T22:09:28.353Z","repository":{"id":36377076,"uuid":"201802102","full_name":"LFDT-web3j/web3j-unit","owner":"LFDT-web3j","description":"Smart contract testing framework via integrated EVM and various Ethereum clients","archived":false,"fork":false,"pushed_at":"2025-04-10T09:20:32.000Z","size":2084,"stargazers_count":25,"open_issues_count":2,"forks_count":23,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-08T11:44:08.538Z","etag":null,"topics":["blockchain","docker","ethereum","geth","parity","testing","web3j"],"latest_commit_sha":null,"homepage":"https://www.web3labs.com/epirus","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LFDT-web3j.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["web3j"]}},"created_at":"2019-08-11T18:42:16.000Z","updated_at":"2025-04-10T09:20:36.000Z","dependencies_parsed_at":"2024-01-05T09:40:41.739Z","dependency_job_id":"45540d4c-7254-4fe3-ae05-fd468d05cde0","html_url":"https://github.com/LFDT-web3j/web3j-unit","commit_stats":null,"previous_names":["hyperledger/web3j-unit","web3j/web3j-unit","lfdt-web3j/web3j-unit","hyperledger-web3j/web3j-unit"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/LFDT-web3j/web3j-unit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LFDT-web3j%2Fweb3j-unit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LFDT-web3j%2Fweb3j-unit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LFDT-web3j%2Fweb3j-unit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LFDT-web3j%2Fweb3j-unit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LFDT-web3j","download_url":"https://codeload.github.com/LFDT-web3j/web3j-unit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LFDT-web3j%2Fweb3j-unit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263120777,"owners_count":23416881,"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":["blockchain","docker","ethereum","geth","parity","testing","web3j"],"created_at":"2025-06-08T11:30:42.386Z","updated_at":"2026-01-19T22:09:28.347Z","avatar_url":"https://github.com/LFDT-web3j.png","language":"Kotlin","funding_links":["https://github.com/sponsors/web3j"],"categories":[],"sub_categories":[],"readme":"# Web3j-unit [![Build Status](https://github.com/web3j/web3j-unit/actions/workflows/build.yml/badge.svg)](https://github.com/web3j/web3j-unit/actions/workflows/build.yml)\n\nWeb3j-unit is a [Junit 5](https://junit.org/junit5/docs/current/user-guide/) extension to streamline the creation of Ethereum contract tests.\n\nMultiple Ethereum implementations are supported including Geth and Besu. To run tests built using Web3j-unit, **docker is required** on the host.\n\nInstances of `Web3j`, `TransactionManager` and `GasProvider` are injected into the Junit runner.\n\nYou can find a sample [here](https://github.com/web3j/web3j-unitexample).\n\nYou can find an example using docker-compose [here](https://github.com/web3j/web3j-unit-docker-compose-example). This spins up VMWare Concord nodes using a docker-compose file. \n\n### Getting Started\n\n1. Add dependency to gradle.\n\n```groovy\n   repositories {\n      mavenCentral()\n      maven { url \"https://hyperledger.jfrog.io/artifactory/besu-maven/\" }\n      maven { url \"https://artifacts.consensys.net/public/maven/maven/\" }\n      maven { url \"https://splunk.jfrog.io/splunk/ext-releases-local\" }\n      maven { url \"https://dl.cloudsmith.io/public/consensys/quorum-mainnet-launcher/maven/\" }\n   }\n\n   implementation \"org.web3j:core:4.14.0\"\n   testCompile \"org.web3j:web3j-unit:4.14.0\"\n```\n\n2. Create a new test with the `@EVMTest` annotation. An embedded EVM is used by default. To use Geth or Besu pass the node type into the annotation: `@EVMTest(NodeType.GETH)` or `@EVMTest(NodeType.BESU)`\n\n```kotlin\n@EVMTest\nclass GreeterTest {\n\n}\n```\n\n3. Inject instance of `Web3j` `TransactionManager` and `ContractGasProvider` in your test method.\n\n```kotlin\n@EVMTest\nclass GreeterTest {\n\n    @Test\n    fun greeterDeploys(\n        web3j: Web3j,\n        transactionManager: TransactionManager,\n        gasProvider: ContractGasProvider\n    ) {}\n\n}\n```\n\n4. Deploy your contract in the test.\n\n```kotlin\n@EVMTest\nclass GreeterTest {\n\n    @Test\n    fun greeterDeploys(\n        web3j: Web3j,\n        transactionManager: TransactionManager,\n        gasProvider: ContractGasProvider\n    ) {\n        val greeter = Greeter.deploy(web3j, transactionManager, gasProvider, \"Hello EVM\").send()\n        val greeting = greeter.greet().send()\n        assertEquals(\"Hello EVM\", greeting)\n    }\n\n}\n```\n\n5. Run the test!\n\n### Using a custom docker-compose file\n\n1. Add dependency to gradle.\n   \n```groovy\n  repositories {\n     mavenCentral()\n  }\n\n  implementation \"org.web3j:core:5.0.1\"\n  testCompile \"org.web3j:web3j-unit:5.0.1\"\n```\n\n2. Create a new test with the `@EVMComposeTest` annotation.\nBy default, uses `test.yml` file in the project home, and runs `web3j` on service name `node1` exposing the port `8545`. \nCan be customised to use specific docker-compose file, service name and port by `@EVMComposeTest(\"src/test/resources/geth.yml\", \"ethnode1\", 8080)`\nHere, we connect to the service named `ethnode1` in the `src/test/resources/geth.yml` docker-compose file which exposes the port `8080` for `web3j` to connect to. \n\n```kotlin\n@EVMComposeTest(\"src/test/resources/geth.yml\", \"ethnode1\", 8080)\nclass GreeterTest {\n\n}\n```\n\n3. Inject instance of `Web3j` `TransactionManager` and `ContractGasProvider` in your test method.\n\n```kotlin\n@EVMComposeTest(\"src/test/resources/geth.yml\", \"ethnode1\", 8080)\nclass GreeterTest {\n\n    @Test\n    fun greeterDeploys(\n        web3j: Web3j,\n        transactionManager: TransactionManager,\n        gasProvider: ContractGasProvider\n    ) {}\n\n}\n```\n\n4. Deploy your contract in the test.\n\n```kotlin\n@EVMComposeTest(\"src/test/resources/geth.yml\", \"ethnode1\", 8080)\nclass GreeterTest {\n\n    @Test\n    fun greeterDeploys(\n        web3j: Web3j,\n        transactionManager: TransactionManager,\n        gasProvider: ContractGasProvider\n    ) {\n        val greeter = Greeter.deploy(web3j, transactionManager, gasProvider, \"Hello EVM\").send()\n        val greeting = greeter.greet().send()\n        assertEquals(\"Hello EVM\", greeting)\n    }\n\n}\n```\n\n5. Run the test!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flfdt-web3j%2Fweb3j-unit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flfdt-web3j%2Fweb3j-unit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flfdt-web3j%2Fweb3j-unit/lists"}