feat(test-utils): Implement Shared Test Utilities for the Arbellar Test Suite

[Adamsonoladipupo]

Implement the shared test utilities package that future Arbellar test suites (unit, integration, security, and e2e) will build on.

The packages/test-utils crate currently contains only an empty #![no_std] module. Its full specification is already documented in packages/test-utils/README.md.

This package removes boilerplate from contract tests by providing reusable helpers for account creation, contract deployment, asset mocks, balance assertions, and time manipulation — in line with Arbellar's documented testing strategy (tests/README.md).

---

📍 File Scope

Applies to:

• packages/test-utils/src/lib.rs
• packages/test-utils/Cargo.toml (add soroban-sdk and arbellar-types dependencies as needed; soroban-sdk test utilities are enabled via its testutils feature where required)

Follow the existing Arbellar workspace conventions and the helper signatures specified in packages/test-utils/README.md.

---

🎯 Objective

Provide a small, documented, and tested set of helpers that make writing Arbellar contract tests fast and consistent:

• Test account creation and funding
• Contract deployment helpers for the Arbellar vault
• Mock asset helpers
• Balance snapshot/assertion utilities
• Time manipulation utilities

---

📝 Implementation Requirements

Account Helpers

pub fn create_test_accounts(env: &Env, count: u32) -> Vec<Address>;

pub fn fund_test_account(env: &Env, account: &Address, amount: i128);

Contract Deployment Helpers

pub fn deploy_arbellar_vault(env: &Env) -> ContractClient;

pub fn deploy_and_initialize(
    env: &Env,
    admin: &Address,
    treasury: &Address,
) -> ContractClient;

• deploy_and_initialize must call initialize(admin, treasury) on the deployed contract (matching the vault contract's initialize entry point from the vault issue).
• The vault WASM can be embedded via include_bytes! from the release build target directory (document the required build step in a doc comment) or registered using the Soroban SDK's env.register_contract_wasm(...) pattern shown in the spec.

Asset Mocks

pub fn create_mock_usdc(env: &Env) -> Address;

pub fn create_mock_xlm(env: &Env) -> Address;

Assertion Utilities

pub fn assert_vault_balance(
    env: &Env,
    contract: &ContractClient,
    user: &Address,
    asset: &Address,
    expected: i128,
);

Time Utilities

pub fn advance_time(env: &Env, seconds: u64);

pub fn current_time(env: &Env) -> u64;

Optional Extras (if straightforward)

• create_test_execution_params(...) per the spec.
• take_balance_snapshot(...) / assert_balance_changes(...) per the spec.

Keep the scope small: do not implement integration or security test scenarios — only the reusable helpers.

---

🧪 Verification

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features --package arbellar-test-utils
cargo build --target wasm32-unknown-unknown --release

Verify:

• Helpers compile and the package builds for the workspace
• A minimal self-test (e.g., create a test account, fund it, deploy + initialize the vault, run a deposit/withdraw round-trip using the helpers) passes
• No lint warnings
• Public helpers are documented with /// doc comments

---

✅ Acceptance Criteria

• create_test_accounts / fund_test_account are implemented
• deploy_arbellar_vault / deploy_and_initialize deploy and initialize the vault contract correctly
• create_mock_usdc / create_mock_xlm provide working mock assets
• assert_vault_balance raises a clear assertion on mismatch
• advance_time / current_time manipulate the ledger timestamp correctly
• A minimal example test using the helpers runs successfully
• Public functions are documented
• cargo fmt --all -- --check passes
• cargo clippy --all-targets --all-features -- -D warnings passes
• cargo build --target wasm32-unknown-unknown --release succeeds
• Uses types from arbellar-types where applicable instead of redefining them

---

🌿 Suggested Branch

git checkout -b feat/shared-test-utils

---

📝 Suggested Commit Message

feat(test-utils): implement shared test utilities for the Arbellar test suite

---

📦 PR Requirements

• Assignment required before starting
• Time Limit: ETA 24 hrs