Merge pull request #558 from Ekenesamuel8/kenesam

Add configurable contract load testing suite

Author: LaGodxy

.cargo/config.toml

@@ -8,4 +8,4 @@ linker = "clang"
 linker = "clang"
 
 [build]
-target = "x86_64-pc-windows-gnu"
+target = "x86_64-pc-windows-gnu"

.github/workflows/ci.yml

@@ -162,6 +162,47 @@ jobs:
           name: perf-report
           path: target/perf_report.json
 
+  load-testing:
+    name: Load Testing
+    runs-on: ubuntu-latest
+    env:
+      STRELLER_PEAK_LOAD: 5
+      STRELLER_LOAD_MULTIPLIER: 10
+      STRELLER_STUDENT_POOL: 20
+      STRELLER_COURSE_COUNT: 4
+      STRELLER_READ_MULTIPLIER: 2
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-load-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-load-
+            ${{ runner.os }}-cargo-
+
+      - name: Make scripts executable
+        run: chmod +x scripts/*.sh
+
+      - name: Run bounded load test suite
+        run: ./scripts/load_test.sh --ci --report target/load-test-report.json --summary target/load-test-summary.md
+
+      - name: Upload load test artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: load-test-report
+          path: |
+            target/load-test-report.json
+            target/load-test-summary.md
+
   visual-regression:
     name: Visual Regression
     runs-on: ubuntu-latest
@@ -248,6 +289,7 @@ jobs:
             echo "Test: ${{ needs.test.result }}"
             echo "Coverage: ${{ needs.coverage.result }}"
             echo "Performance: ${{ needs.performance.result }}"
+            echo "Load Testing: ${{ needs.load-testing.result }}"
             echo "Visual Regression: ${{ needs.visual-regression.result }}"
             echo "Accessibility: ${{ needs.accessibility.result }}"
             exit 1

Makefile

@@ -2,7 +2,7 @@
 # 
 # This Makefile provides convenient commands for development and testing
 
-.PHONY: help build test unit-test e2e-test localnet-start localnet-stop localnet-status clean deploy-testnet deploy-mainnet fmt lint lint-style pre-commit-install pre-commit-run coverage coverage-html coverage-lcov coverage-open security-scan security-scan-full perf-profile perf-baseline ci-security ci-coverage ci-perf test-coverage-comprehensive test-coverage-unit test-coverage-integration test-coverage-property test-coverage-edge-cases test-coverage-errors test-coverage-performance test-coverage-report coverage-threshold coverage-badge coverage-dashboard
+.PHONY: help build test unit-test e2e-test localnet-start localnet-stop localnet-status clean deploy-testnet deploy-mainnet fmt lint lint-style pre-commit-install pre-commit-run coverage coverage-html coverage-lcov coverage-open security-scan security-scan-full perf-profile perf-baseline load-test load-test-ci ci-security ci-coverage ci-perf test-coverage-comprehensive test-coverage-unit test-coverage-integration test-coverage-property test-coverage-edge-cases test-coverage-errors test-coverage-performance test-coverage-report coverage-threshold coverage-badge coverage-dashboard
 
 # Colors for output
 GREEN=\033[0;32m
@@ -57,6 +57,8 @@ help:
 	@echo "  $(RED)security-scan-full$(NC)  - Full security scan including semgrep"
 	@echo "  $(RED)perf-profile$(NC)        - Performance profile all contracts"
 	@echo "  $(RED)perf-baseline$(NC)       - Save performance baseline"
+	@echo "  $(RED)load-test$(NC)           - Run configurable contract load tests and write reports"
+	@echo "  $(RED)load-test-ci$(NC)        - Run bounded load tests with CI-safe defaults"
 	@echo ""
 	@echo "Examples:"
 	@echo "  make e2e-test              # Full E2E test cycle"
@@ -267,6 +269,18 @@ perf-compare:
 	chmod +x ./scripts/perf_profile.sh
 	./scripts/perf_profile.sh --compare target/perf_baseline.json
 
+# Run the contract load-test suite with local defaults.
+load-test:
+	@echo "$(RED)[LOAD]$(NC) Running load test suite..."
+	chmod +x ./scripts/load_test.sh
+	./scripts/load_test.sh
+
+# Run the load-test suite with CI-safe bounded defaults.
+load-test-ci:
+	@echo "$(RED)[LOAD]$(NC) Running CI-safe load test suite..."
+	chmod +x ./scripts/load_test.sh
+	./scripts/load_test.sh --ci
+
 # ─────────────────────────────────────────────────────────────
 # CI convenience targets
 # ─────────────────────────────────────────────────────────────

README.md

@@ -194,6 +194,25 @@ Run unit tests to ensure everything is functioning as expected:
 cargo test
 ```
 
+#### Load Testing
+
+Run the bounded contract load-testing suite locally:
+
+```bash
+./scripts/load_test.sh
+```
+
+Or with Make / Cargo:
+
+```bash
+make load-test
+cargo load-test -- --report target/load-test-report.json --summary target/load-test-summary.md
+```
+
+The suite uses a default `STRELLER_LOAD_MULTIPLIER=10` to simulate 10x peak load, writes JSON and Markdown reports to `target/`, and has a CI-safe mode available via `./scripts/load_test.sh --ci`.
+
+See [docs/LOAD_TESTING.md](docs/LOAD_TESTING.md) for the configurable load variables and report format.
+
 #### Property-Based Tests
 
 We use `proptest` to verify contract invariants with random inputs:

docs/LOAD_TESTING.md

@@ -1,44 +1,44 @@
-# StrellerMinds Load Testing & Performance Benchmarks
+# StrellerMinds Load Testing
 
-This document outlines the load testing suite and performance benchmarks implemented for the StrellerMinds smart contracts.
+This repository includes a contract load-testing suite for scalability and performance benchmarking. The suite runs in Soroban's host-side test environment, which keeps CI stable while still stressing contract execution paths, storage writes, and repeated reads at a configurable 10x peak multiplier.
 
-## 🚀 Overview
+## What the suite measures
 
-The load testing suite is designed to evaluate how the system behaves under stress, specifically focusing on transaction throughput, resource consumption (CPU/Memory), and latency when multiple users interact with the contracts.
+- Latency and duration per scenario
+- Throughput in operations per second
+- Failed operations
+- Emitted contract events
+- Estimated persistent state writes
+- Process RSS memory delta on Linux runners when available
+- Bottleneck notes generated from p95 latency, throughput, and write intensity heuristics
 
-## 📁 Structure
+## Scenarios
 
 -   **E2E Load Tests**: Located in `e2e-tests/tests/load_testing.rs`. These tests run against a live Soroban network (e.g., localnet).
 -   **Internal Benchmarks**: Located in `contracts/token/src/benchmarks.rs`. These are unit tests that measure execution efficiency within the `soroban-sdk` test environment.
 -   **CI/CD Integration**: Automated daily runs via GitHub Actions (`.github/workflows/load-testing.yml`) to track baseline metrics and alert on performance regressions.
 
-## 🧪 Load Scenarios
+1. `progress-write-hot-path`
+   Runs repeated `record_progress` calls against a tight course set to stress hot writes.
+2. `progress-write-multi-course`
+   Spreads `record_progress` calls across more courses to grow student course lists and storage churn.
+3. `progress-read-heavy`
+   Seeds progress data, then benchmarks `get_progress` and `get_student_courses` under sustained reads.
 
 ### 1. High Volume Analytics Recording
 -   **Scenario**: Simulates multiple students recording learning sessions simultaneously.
 -   **Component**: `analytics` contract.
 -   **Goal**: Measure throughput (ops/sec) and ensure non-blocking transaction flow.
 -   **Running**: `LOAD_TEST_REQUESTS=10000 cargo test --test load_testing test_load_analytics_recording_stress -- --ignored`
 
-### 2. Leaderboard Generation Performance
--   **Scenario**: Measures the time taken to generate leaderboards with a large set of student data.
--   **Component**: `analytics` contract.
--   **Goal**: Ensure leaderboard sorting and calculation remain efficient as the user base grows.
--   **Running**: `cargo test --test load_testing test_load_leaderboard_generation_performance -- --ignored`
+The runner simulates:
 
-### 3. Diagnostics Monitoring Overhead
--   **Scenario**: Compares transaction execution time with and without active diagnostics monitoring.
--   **Component**: `diagnostics` & `token` contracts.
--   **Goal**: Quantify the performance "cost" of real-time monitoring.
--   **Running**: `cargo test --test load_testing test_load_diagnostics_overhead -- --ignored`
+- `peak load * load multiplier` write operations
+- `(peak load * load multiplier) * read multiplier` read operations
 
-### 4. Token Mint/Transfer Load
--   **Scenario**: Performs 100+ mint and transfer operations in a single test environment.
--   **Component**: `token` contract.
--   **Goal**: Benchmark gas efficiency and CPU budget utilization.
--   **Running**: `cargo test -p token benchmark_token_load`
+By default, the multiplier is `10`, which gives the required 10x peak simulation. All values are configurable through environment variables.
 
-## 📊 Success Criteria
+## Local usage
 
 | Metric | Target |
 | :--- | :--- |
@@ -47,20 +47,87 @@ The load testing suite is designed to evaluate how the system behaves under stre
 | Diagnostics Overhead | < 15% CPU increase |
 | Recovery Time | < 5s after surge |
 
-## 🛠️ Monitoring Load Performance
+```bash
+./scripts/load_test.sh
+```
+
+Or through cargo:
+
+```bash
+cargo load-test -- --report target/load-test-report.json --summary target/load-test-summary.md
+```
+
+Or through Make:
+
+```bash
+make load-test
+```
+
+## CI-safe usage
+
+The CI workflow uses bounded defaults to keep the job deterministic:
+
+```bash
+./scripts/load_test.sh --ci
+```
+
+Or:
+
+```bash
+make load-test-ci
+```
+
+## Environment variables
+
+| Variable | Purpose | Local Default | CI Default |
+| --- | --- | ---: | ---: |
+| `STRELLER_PEAK_LOAD` | Baseline peak load before multiplying | `25` | `5` |
+| `STRELLER_LOAD_MULTIPLIER` | Stress multiplier | `10` | `10` |
+| `STRELLER_STUDENT_POOL` | Number of simulated students | `50` | `20` |
+| `STRELLER_COURSE_COUNT` | Number of simulated courses | `8` | `4` |
+| `STRELLER_READ_MULTIPLIER` | Read operations per seeded write | `3` | `2` |
+
+Example:
+
+```bash
+STRELLER_PEAK_LOAD=40 \
+STRELLER_LOAD_MULTIPLIER=10 \
+STRELLER_STUDENT_POOL=80 \
+STRELLER_COURSE_COUNT=12 \
+./scripts/load_test.sh
+```
+
+## Reports
+
+Each run produces:
+
+- `target/load-test-report.json` - machine-readable metrics for CI artifacts
+- `target/load-test-summary.md` - human-readable scenario summary and bottleneck notes
+
+You can override both paths with:
+
+```bash
+./scripts/load_test.sh --report target/custom-load-report.json --summary target/custom-load-summary.md
+```
+
+## Reading the output
+
+Focus on these fields first:
+
+- `throughput_ops_per_sec`
+- `avg_latency_ms`
+- `p95_latency_ms`
+- `failed_operations`
+- `estimated_state_writes`
 
-We use the `diagnostics` contract to monitor performance during load tests. Key metrics tracked include:
--   `average_execution_time`: Average time per transaction.
--   `gas_used`: Resource consumption per operation.
--   `error_rate`: Percentage of failed transactions under load.
+If the generated bottleneck notes mention tail latency or write intensity, the usual next step is to inspect storage-heavy contract code paths, symbol creation patterns, and list growth in persistent storage.
 
-## 📝 Reviewing Effectiveness
+## CI integration
 
-Load tests should be reviewed:
-1.  **After major refactors**: To ensure no performance regressions.
-2.  **Before mainnet deployment**: To validate system capacity.
-3.  **When adding new features**: To check impact on existing throughput.
+The main CI workflow includes a dedicated `Load Testing` job that:
 
----
+1. Uses bounded environment defaults
+2. Runs `./scripts/load_test.sh --ci`
+3. Uploads the JSON and Markdown reports as workflow artifacts
 
-*Verified on: 2026-03-27*
+This keeps the suite safe for pull requests while still catching regressions in latency, throughput, and storage-heavy paths.

scripts/load_test.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPORT_PATH="${ROOT_DIR}/target/load-test-report.json"
+SUMMARY_PATH="${ROOT_DIR}/target/load-test-summary.md"
+CI_MODE=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --report)
+            shift
+            REPORT_PATH="${1:?missing report path}"
+            shift
+            ;;
+        --summary)
+            shift
+            SUMMARY_PATH="${1:?missing summary path}"
+            shift
+            ;;
+        --ci)
+            CI_MODE=1
+            shift
+            ;;
+        -h|--help)
+            cat <<'EOF'
+StrellerMinds load-test wrapper
+
+Usage:
+  ./scripts/load_test.sh [--ci] [--report <path>] [--summary <path>]
+
+Environment:
+  STRELLER_PEAK_LOAD
+  STRELLER_LOAD_MULTIPLIER
+  STRELLER_STUDENT_POOL
+  STRELLER_COURSE_COUNT
+  STRELLER_READ_MULTIPLIER
+EOF
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [[ "${CI_MODE}" -eq 1 ]]; then
+    export STRELLER_PEAK_LOAD="${STRELLER_PEAK_LOAD:-5}"
+    export STRELLER_LOAD_MULTIPLIER="${STRELLER_LOAD_MULTIPLIER:-10}"
+    export STRELLER_STUDENT_POOL="${STRELLER_STUDENT_POOL:-20}"
+    export STRELLER_COURSE_COUNT="${STRELLER_COURSE_COUNT:-4}"
+    export STRELLER_READ_MULTIPLIER="${STRELLER_READ_MULTIPLIER:-2}"
+    RUNNER_ARGS=(--ci)
+else
+    export STRELLER_PEAK_LOAD="${STRELLER_PEAK_LOAD:-25}"
+    export STRELLER_LOAD_MULTIPLIER="${STRELLER_LOAD_MULTIPLIER:-10}"
+    export STRELLER_STUDENT_POOL="${STRELLER_STUDENT_POOL:-50}"
+    export STRELLER_COURSE_COUNT="${STRELLER_COURSE_COUNT:-8}"
+    export STRELLER_READ_MULTIPLIER="${STRELLER_READ_MULTIPLIER:-3}"
+    RUNNER_ARGS=()
+fi
+
+mkdir -p "$(dirname "${REPORT_PATH}")"
+mkdir -p "$(dirname "${SUMMARY_PATH}")"
+
+cd "${ROOT_DIR}"
+cargo run -p load-test-runner -- "${RUNNER_ARGS[@]}" --report "${REPORT_PATH}" --summary "${SUMMARY_PATH}"

utils/load-test-runner/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "load-test-runner"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+
+[dependencies]
+progress = { path = "../../contracts/progress" }
+soroban-sdk = { workspace = true, features = ["testutils"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"