Add integration tests for under-tested soroban modules

[Meshmulla]

Background

The Soroban workspace has grown to roughly 33 modules under soroban/src/, but the soroban/tests/ directory contains dedicated integration tests for only a handful of them — asset locking, operator rotation, source trust, threshold window, and version migration. That leaves a number of important modules — for example governance, circuit_breaker, and submission_pause — without dedicated end-to-end coverage of their public behavior.

For on-chain code, "it compiles and the unit assertions pass" is not the same as "its entrypoints behave correctly, enforce the right authorization, honor their guards, and emit the right events." Those properties are what integration tests against the contract's public interface actually verify, and for several modules they currently go unverified.

Why this matters

Contracts are hard to change after deployment and unforgiving when wrong, so the behavioral contract of each module — who may call what, what happens when paused or when a breaker is tripped, and which events observers depend on — deserves explicit tests. Beyond catching regressions, these tests serve as executable documentation of each module's intended behavior, which is invaluable as more contributors touch the code.

What needs to be done

• Pick a focused subset to start with (suggested: governance, circuit_breaker, submission_pause) so the PR stays reviewable.
• For each chosen module, add integration tests under soroban/tests/, mirroring the style of the existing suites (e.g. operator_rotation.test.rs, version_migration_tests.rs), that exercise its public entrypoints across:
  • the happy path (valid calls produce the expected state),
  • authorization enforcement (admin/owner gates reject unauthorized callers),
  • guard/pause behavior (operations are correctly blocked when paused or when a breaker is open),
  • emitted events (the right events fire with the right data).
• Reuse the shared setup helpers the existing suites already use, rather than duplicating harness code.
• Keep the tests fully deterministic so they run in the standard cargo test CI job with no special setup.

Where to look

• soroban/src/ — the target modules (governance.rs, circuit_breaker.rs, submission_pause.rs, and the rest of the ~33)
• soroban/tests/ — existing suites to model the style and setup on
• docs/API_REFERENCE.md, docs/EVENTS.md, docs/ERRORS.md — the documented behavior to assert against

Acceptance criteria

• Dedicated integration tests added for at least the three suggested modules, covering happy path, authorization, guards/pause, and events
• Tests reuse the shared setup helpers and run in the standard cargo test CI job
• No existing tests regress, and clippy/fmt stay clean
• CI checks must be green before the PR can be merged

[celina005]

Understanding the ask: ~33 modules under soroban/src/, only a handful have dedicated integration suites. I'd close that gap for the three suggested modules — adding tests that verify actual on-chain behavior (auth, guards, events), not just unit-level logic — reusing existing harness patterns rather than inventing new ones.

My approach, step by step:

Study the existing suites first. Read operator_rotation.test.rs, version_migration_tests.rs, and the other existing integration tests to extract the shared conventions: which setup helpers they call (test env bootstrap, contract deploy/init, identity/auth stubbing), how they simulate authorized vs. unauthorized callers, how they assert emitted events, and file/module naming. Whatever shared fixtures already exist (a test_utils module, a common setup() helper), I reuse directly rather than duplicating.
Read the documented behavioral contract before touching code. For each of the three modules, cross-reference docs/API_REFERENCE.md (entrypoints and their expected params/returns), docs/EVENTS.md (which events must fire and with what data), and docs/ERRORS.md (which error variants correspond to which failure modes). Tests should assert against documented behavior, not just whatever the current implementation happens to do — if I find the code diverges from the docs, I'll flag it separately rather than silently testing the (possibly wrong) implementation.
Map each module's public surface. For governance.rs, circuit_breaker.rs, submission_pause.rs, list every public entrypoint, its auth requirements (admin-only, owner-only, open), and any guard it's subject to (pausable, breaker-gated). This becomes the checklist each test file needs to satisfy.
Write one integration test file per module, named to match the existing convention (e.g. governance_tests.rs / governance.test.rs — whichever the codebase uses), each covering the four required dimensions:
Happy path — valid calls from an authorized caller produce the expected resulting state (read it back via the contract's getters, don't just assert "no panic").
Authorization enforcement — calls from a non-admin/non-owner address are rejected with the correct error variant; verify state is unchanged after the rejected call.
Guard/pause behavior — for submission_pause and any pausable entrypoints in the other two: operations succeed when unpaused, are blocked with the correct error when paused, and (if applicable) resume correctly after unpausing. For circuit_breaker: operations succeed when the breaker is closed, are blocked when tripped/open, and behave correctly on reset — including testing the trip condition itself if it's programmatic rather than purely admin-triggered.
Events — assert the exact event(s) fire on each successful state-changing call, with the right topic/data, per docs/EVENTS.md; also assert no event fires on a rejected/blocked call.
Cover the interaction surface between modules where relevant. E.g. if submission_pause gates entrypoints that governance or circuit_breaker also touch, make sure at least one test exercises that combination (paused + governance call) rather than testing each module in total isolation if the real contract wiring means they compose.
Keep everything deterministic. No wall-clock time, no external randomness — use whatever fixed-ledger-timestamp/fixed-seed pattern the existing suites use for anything time- or order-sensitive (e.g. if governance has voting windows or timelocks). This is a hard requirement since these need to run in standard cargo test CI with no special setup.
Validate locally before opening the PR:
cargo test — new tests pass, and I'll deliberately break one guard/auth check locally first to confirm the corresponding test actually fails (proving it tests something real, not just exercising the happy path).
cargo clippy -- -D warnings and cargo fmt --check — clean.
Confirm no existing test regresses.
Keep the diff surgical. New test files under soroban/tests/ (plus any minimal additions to shared setup helpers if a fixture genuinely needs extending for these modules — called out explicitly in the PR body, not silently mixed into module source changes). No changes to soroban/src/ unless a genuine testability gap turns up, in which case I flag it rather than bundle a fix into this PR.

Deliverable: three new integration test files (governance, circuit_breaker, submission_pause), reusing shared setup helpers, running in the standard cargo test job, each demonstrably covering happy path / auth / guards / events with a PR description mapping each test back to the documented behavior it verifies.

[grantfox-oss]

🦊 GrantFox — @celina005 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #32)
2. Your PR will be reviewed by the stellar-kracken maintainers

Good luck! Track your progress on GrantFox.