Skip to content

feat: Integration test helper#103

Open
tuliomir wants to merge 4 commits intomasterfrom
feat/integration-test-helper
Open

feat: Integration test helper#103
tuliomir wants to merge 4 commits intomasterfrom
feat/integration-test-helper

Conversation

@tuliomir
Copy link
Contributor

The Integration Test Helper is a dockerized HTTP service that provides race-condition-free wallet generation and funding for hathor-wallet-lib integration tests.

It pre-generates BIP39 wallets with derived addresses outside the test runtime (avoiding prohibitive address derivation costs under Jest) and splits the genesis block's single UTXO into a pool of independent, readily-available UTXOs so that parallel test executions never compete for funds.

See rendered.

@tuliomir tuliomir self-assigned this Feb 25, 2026
@tuliomir tuliomir moved this from Todo to In Progress (Done) in Hathor Network Feb 25, 2026
@tuliomir tuliomir force-pushed the feat/integration-test-helper branch 2 times, most recently from 055f648 to f195c66 Compare March 6, 2026 14:39

When `testUtxos.length` drops below `REFILL_THRESHOLD` (default 10)
after a funding operation, the service triggers a background split of
the current `largeUtxo`. The split is delayed by 1.5 seconds to avoid
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wait X seconds for the tx to be accepted usually introduces race conditions, a solution we have on the wallet-lib itself is waiting for both wallets to receive the transaction, this way we always wait until it is ready to use again.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea of having a buffer of transactions is exactly to prevent race conditions: the tests have another 1.5 seconds to request more transactions while the buffer is re-filled.

It is not necessary to wait for the tx to be received by the wallet, because the utxo is guaranteed to be isolated for that test alone.

If this becomes not enough we can increase the threshold to 20, for example. Another option, if the DevMiner ( #102 ) becomes efficient enough, is to reduce the delay from 1500ms to less than that.

@@ -0,0 +1,439 @@
- Feature Name: integration-test-helper
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated to line

I got a couple os suggestions for the service:

Define a consistent error response schema, e.g.: { "error": "POOL_EXHAUSTED", "message": "No UTXOs available", "retryable": true }
This creates possible recoverable actions like retry and makes the reason of failure easier to spot.

Increate log observability with test names, meaning that on all requests we send the test name and the service logger will include the test name on the logs.
This way we can search for the test name and get the logs from their requests, this would make debugging any issues easier in the future

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good points, thanks!

  1. Added an error schema on 3357814

  2. Added the test name feature on 3006b32

@tuliomir tuliomir moved this from In Progress (Done) to In Progress (WIP) in Hathor Network Mar 16, 2026
Define a standardized error response format with machine-readable codes,
human-readable messages, and a retryable flag to enable smart retry logic
in test harnesses.
Introduce an optional X-Test-Name header accepted by all endpoints.
The service threads the test name through every log line for that
request's lifecycle, enabling log search by test name when debugging
failures in parallel test runs.
@tuliomir tuliomir moved this from In Progress (WIP) to In Progress (Done) in Hathor Network Mar 17, 2026
@tuliomir tuliomir requested a review from r4mmer March 17, 2026 14:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress (Done)

Development

Successfully merging this pull request may close these issues.

2 participants