MultiversX Testing Handbook Skill

MultiversX Testing Handbook

This skill provides expert guidance on the 3 layers of MultiversX testing: RustVM Unit Tests, Mandos Integration Tests, and Chain Simulation.

1. RustVM Unit Tests

Location: #[cfg(test)] modules within contract files or tests/ directory.
Speed: Instant.
Scope: Internal logic, strict math, private functions.
Mocking: Use multiversx_sc_scenario::imports::* to mock the blockchain environment (blockchain_mock.set_caller(addr)).

2. Mandos Scenarios (`.scen.json`)

Location: scenarios/ directory.
Requirement: "If it's an endpoint, it MUST have a Mandos test."
Execution:
- cargo test-gen generates Rust wrappers for scenarios.
- cargo test runs them.
Key Concepts:
- step: setState: Initialize accounts and balances.
- step: scCall: Execute endpoint.
- step: checkState: Verify storage matches expected values.

3. Chain Simulator (`mx-chain-simulator-go`)

Location: Separate system test suite (often Go or Python).
Scope: Interaction with Node API, complex cross-shard reorgs, off-chain indexing.
Tool: Use POST /simulator/generate-blocks to force execution.

4. Coverage Strategy

Money In/Out: 100% Mandos coverage required.
View Functions: Unit test coverage sufficient.
Access Control: Explicit negative tests (expect error 4) for unauthorized calls.
Endpoint Coverage: Every #[endpoint] must have at least one Mandos scenario.
Payable Endpoints: Every #[payable] endpoint must test: correct token, wrong token, zero amount, unauthorized caller.
Role-Gated Endpoints: Every #[only_owner] / #[only_role] must have a negative test (unauthorized caller → expect error).
State Transitions: State transitions must be verified with checkState in Mandos.

5. Test Quality Scoring Rubric

Score each category, then average for overall score.

| Category | 0-2 (Poor) | 3-5 (Partial) | 6-8 (Good) | 9-10 (Excellent) | |----------|-----------|---------------|------------|-------------------| | Unit Tests | No tests | Some functions tested | Core logic covered | All functions + edge cases | | Mandos Coverage | No scenarios | Some endpoints covered | All endpoints covered | All endpoints + error paths | | Access Control Tests | No auth tests | Owner-only tested | All roles tested | All roles + negative tests | | Money Flow Tests | No payment tests | Happy path only | All payment endpoints | Happy + error + edge amounts | | Chain Simulator | Not available | Setup exists, not run | Basic flows tested | Cross-shard + reorg tested |

Scoring Formula

Start at 5 (baseline for "tests exist and pass").
+1 for each category rated Good (6-8).
+2 for each category rated Excellent (9-10).
-1 for each category rated Poor (0-2).
-2 if Chain Simulator is not available.
Cap at 10, floor at 1.

6. Output Format

Test Quality Report

Test Execution:
  cargo test: [pass/fail/skip counts]
  Mandos scenarios: [pass/fail counts]
  Chain Simulator: [available: Y/N] [pass/fail if available]

Coverage Assessment:
  Endpoints with Mandos: [N/total] ([%])
  Payable endpoints fully tested: [N/total]
  Access control negative tests: [N/total]
  State transition checks: [N/total]

Category Scores:
  Unit Tests: [0-10]
  Mandos Coverage: [0-10]
  Access Control Tests: [0-10]
  Money Flow Tests: [0-10]
  Chain Simulator: [0-10]

Overall Score: [1-10]

Gaps:
- [list of endpoints without tests]
- [list of missing negative tests]
- [list of untested payment scenarios]

Completion Criteria

Test quality assessment is complete when:

All tests have been executed (cargo test + Mandos).
Every category in the scoring rubric has been evaluated.
Overall score is calculated.
Gaps are documented.

Agent Skills: MultiversX Testing Handbook

Install this agent skill to your local

Skill Files