wiremock-test

# WireMock RPC Test Proxy You manage a WireMock proxy that sits between the relayer and an RPC endpoint. It forwards traffic normally, but can inject mock error responses on demand. ## Project paths - Docker compose: `testing/wiremock/docker-compose.yaml` - Generic mappings: `testing/wiremock/mappings/generic/` (work with any JSON-RPC network) - Stellar mappings: `testing/wiremock/mappings/stellar/` - Future EVM mappings: `testing/wiremock/mappings/evm/` (not yet created) - Helper scripts: `testing/wiremock/scripts/` ## Available scenarios ### Generic (any network) | Scenario name | Shorthand | What it does | |---|---|---| | `rpc-timeout` | `timeout` | 30s delay on next RPC call (any method) | | `rpc-500` | `500` | HTTP 500 on next RPC call | | `rpc-connection-reset` | `reset` | TCP connection reset on next RPC call | ### Stellar-specific | Scenario name | Shorthand | What it does | |---|---|---| | `stellar-try-again-later` | `tal`, `try-again-later` | Returns `TRY_AGAIN_LATER` on next `sendTransaction` | | `stellar-insufficient-fee` | `fee`, `insufficient-fee` | Returns `ERROR` with `TxInsufficientFee` on next `sendTransaction` | | `stellar-get-transaction-not-found` | `not-found`, `get-tx-not-found` | Returns `NOT_FOUND` for next `getTransaction` | All scenarios fire **exactly once** then revert to proxying real traffic. ## How to handle user arguments ($ARGUMENTS) Based on the argument, execute the matching flow: ### `setup` — requires a network argument **Syntax:** `setup <network> [rpc-url]` A bare `setup` with no network is **not allowed** — ask the user which network they want (stellar or evm). 1. Determine target RPC: - `setup stellar` → default: `https://soroban-testnet.stellar.org` - `setup evm` or `setup anvil` → default: `http://host.docker.internal:8545` - `setup stellar <url>` or `setup evm <url>` → use the provided URL as `WIREMOCK_PROXY_TARGET` 2. Start WireMock: ```bash WIREMOCK_PROXY_TARGET=<target> docker compose -f testing/wiremock/docker-compose.yaml up -d ``` For stellar with default target, just: `docker compose -f testing/wiremock/docker-compose.yaml up -d` 3. Wait for health: poll `curl -sf http://localhost:9090/__admin/health` (retry up to 10 times with 2s sleep) 4. Verify scenarios loaded: `curl -s http://localhost:9090/__admin/scenarios` 5. Remind the user: - WireMock proxy is running on `http://localhost:9090` proxying to `<target>` - To use it, update the relevant network config `rpc_urls` to `["http://localhost:9090"]` - If the relayer runs in Docker, use `http://host.docker.internal:9090` instead - Show only the **relevant** scenarios: generic + the chosen network's specific scenarios - For Stellar: mention updating `config/networks/stellar.json` testnet entry - For EVM: mention updating the relevant EVM network config ### `teardown` or `stop` 1. Run: `docker compose -f testing/wiremock/docker-compose.yaml down` 2. Confirm stopped ### `status` 1. Check if WireMock is running: `docker compose -f testing/wiremock/docker-compose.yaml ps` 2. If running, show scenario states: `curl -s http://localhost:9090/__admin/scenarios` 3. Show recent requests: `curl -s 'http://localhost:9090/__admin/requests?limit=10'` 4. Parse and display in a readable format ### `check-metrics` or `metrics` 1. Fetch relayer metrics: `curl -s http://localhost:8081/debug/metrics/scrape` 2. Filter and display lines matching: `insufficient_fee|try_again_later|transactions_success|transactions_failed|stellar_submission_failures|stellar_try_again_later|rpc_call_latency|api_rpc_failures` 3. Summarize what the metrics show ### A scenario name or shorthand 1. First ensure WireMock is running (check health endpoint, start if needed) 2. Resolve the scenario name — the user may use shorthand: - Generic: `timeout` → `rpc-timeout`, `500` → `rpc-500`, `reset` → `rpc-connection-reset` - Stellar: `try-again-later` or `tal` → `stellar-try-again-later`, `insufficient-fee` or `fee` → `stellar-insufficient-fee`, `not-found` or `get-tx-not-found` → `stellar-get-transaction-not-found` 3. Arm the scenario: ```bash curl -s -X PUT "http://localhost:9090/__admin/scenarios/{scenario-name}/state" \ -H 'Content-Type: application/json' -d '{"state": "armed"}' ``` 4. Verify it's armed by checking the scenario state 5. Tell the user what will happen on the next matching RPC call ### `chaos` or `all-chaos` 1. Ensure WireMock is running 2. Arm ALL scenarios simultaneously 3. Explain what will happen: scenarios are priority-based, so the most specific one fires first ### `reset` 1. Reset all scenarios: `curl -s -X POST http://localhost:9090/__admin/scenarios/reset` 2. Clear request log: `curl -s -X DELETE http://localhost:9090/__admin/requests` 3. Confirm all scenarios are back to initial (inactive) state ## Important reminders Always remind the user about these when relevant: - The relayer's network `rpc_urls` must point to `http://localhost:9090` (or `http://host.docker.internal:9090` from Docker) for WireMock to intercept traffic - After testing, they should revert `rpc_urls` back to the real RPC endpoint - Scenarios are one-shot: they fire once and revert. Re-arm to test again. - The relayer's metrics endpoint is at `http://localhost:8081/debug/metrics/scrape` (configurable via METRICS_PORT) - Generic scenarios (timeout, 500, connection-reset) work with any network — no need to change them when switching between Stellar and EVM testing ## Adding new network support When adding EVM or other network-specific scenarios: 1. Create `testing/wiremock/mappings/<network>/` directory 2. Add scenario JSON files following the existing pattern (use `"requiredScenarioState": "armed"`) 3. Mount the directory in `docker-compose.yaml` (uncomment or add the volume line) 4. Update this skill's scenario tables above 5. Restart WireMock to load new mappings