wiremock-test

name	wiremock-test
description	Manage WireMock proxy for RPC testing. Starts the proxy, arms scenarios to simulate transient errors (timeouts, 500s, connection resets, and network-specific errors like Stellar TRY_AGAIN_LATER), and checks metrics. Use to verify relayer behavior under failure conditions.
allowed-tools	Bash, Read, Grep, Glob, Agent
argument-hint	<scenario> | setup <network> [rpc-url] | teardown | status | check-metrics

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:

   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:

   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