starknet_os_runner: add rpc_records infrastructure for recording and replaying RPC interactions

Author: AvivYossef-starkware

crates/starknet_os_runner/src/running.rs

@@ -15,12 +15,14 @@ pub mod virtual_block_executor;
 #[cfg(test)]
 mod classes_provider_test;
 #[cfg(test)]
+pub mod rpc_records;
+#[cfg(test)]
+mod rpc_records_test;
+#[cfg(test)]
 mod runner_test;
 #[cfg(test)]
 mod storage_proofs_test;
 #[cfg(test)]
-pub mod test_fixtures;
-#[cfg(test)]
 pub mod test_utils;
 #[cfg(test)]
 mod virtual_block_executor_test;

crates/starknet_os_runner/src/running/rpc_records.rs

@@ -0,0 +1,105 @@
+//! Utilities for recording and replaying RPC responses in tests.
+//!
+//! This module provides infrastructure for running integration tests offline
+//! by recording JSON-RPC interactions with real nodes and replaying them
+//! through a mock HTTP server.
+//!
+//! ## Modes
+//!
+//! - **Recording mode** (`RECORD_RPC_RECORDS=1`): Tests run against a real RPC node through a
+//!   recording proxy that saves all request/response pairs to JSON files.
+//!
+//! - **Replay mode** (record files present): Tests start a mock HTTP server that serves
+//!   pre-recorded responses, enabling fully offline execution (used in CI).
+//!
+//! - **Live mode** (default): Tests use a real RPC node directly (existing behavior).
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use apollo_infra_utils::compile_time_cargo_manifest_dir;
+use serde::{Deserialize, Serialize};
+
+/// A recorded JSON-RPC request-response pair.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RpcInteraction {
+    /// The JSON-RPC method name (e.g., "starknet_getStorageAt").
+    pub method: String,
+    /// The JSON-RPC parameters.
+    pub params: serde_json::Value,
+    /// The full JSON-RPC response body.
+    pub response: serde_json::Value,
+}
+
+/// Collection of recorded RPC interactions for a test.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RpcRecords {
+    /// All recorded interactions, in order.
+    pub interactions: Vec<RpcInteraction>,
+}
+
+impl RpcRecords {
+    /// Loads recorded RPC interactions from a JSON file.
+    pub fn load(path: &Path) -> Self {
+        let content = fs::read_to_string(path)
+            .unwrap_or_else(|e| panic!("Failed to read records from {path:?}: {e}"));
+        serde_json::from_str(&content)
+            .unwrap_or_else(|e| panic!("Failed to parse records from {path:?}: {e}"))
+    }
+
+    /// Saves recorded RPC interactions to a JSON file.
+    pub fn save(&self, path: &Path) {
+        let dir = path.parent().expect("Invalid record path");
+        fs::create_dir_all(dir)
+            .unwrap_or_else(|e| panic!("Failed to create directory {dir:?}: {e}"));
+        let content =
+            serde_json::to_string_pretty(self).expect("Failed to serialize RPC records");
+        fs::write(path, content)
+            .unwrap_or_else(|e| panic!("Failed to write records to {path:?}: {e}"));
+    }
+}
+
+/// Creates a mockito server pre-configured with all recorded RPC interactions.
+///
+/// The server matches JSON-RPC requests by their `method` and `params` fields,
+/// returning the recorded response for each matching request.
+/// The `id` and `jsonrpc` version fields are ignored during matching so that
+/// the mock works with both `RpcStateReader` and `JsonRpcClient` regardless
+/// of their internal request formatting.
+pub async fn setup_mock_rpc_server(records: &RpcRecords) -> mockito::ServerGuard {
+    let mut server = mockito::Server::new_async().await;
+    for interaction in &records.interactions {
+        let request_matcher = serde_json::json!({
+            "method": interaction.method,
+            "params": interaction.params,
+        });
+        server
+            .mock("POST", "/")
+            .match_body(mockito::Matcher::PartialJson(request_matcher))
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(serde_json::to_string(&interaction.response).unwrap())
+            .create_async()
+            .await;
+    }
+    server
+}
+
+// ================================================================================================
+// Path helpers
+// ================================================================================================
+
+/// Returns the path to the RPC records directory for the starknet_os_runner crate.
+pub fn records_dir() -> PathBuf {
+    PathBuf::from(compile_time_cargo_manifest_dir!()).join("resources").join("fixtures")
+}
+
+/// Returns the path to a specific test's record file.
+pub fn record_path(test_name: &str) -> PathBuf {
+    records_dir().join(format!("{test_name}.json"))
+}
+
+/// Returns true if a record file exists for the given test.
+pub fn records_exist(test_name: &str) -> bool {
+    record_path(test_name).exists()
+}

crates/starknet_os_runner/src/running/rpc_records_test.rs

@@ -0,0 +1,100 @@
+//! Tests for the RPC records infrastructure.
+
+use crate::running::rpc_records::{
+    setup_mock_rpc_server,
+    RpcInteraction,
+    RpcRecords,
+};
+
+#[test]
+fn test_rpc_records_round_trip_serialization() {
+    let records = RpcRecords {
+        interactions: vec![
+            RpcInteraction {
+                method: "starknet_getStorageAt".to_string(),
+                params: serde_json::json!({
+                    "block_id": {"block_number": 100},
+                    "contract_address": "0x1",
+                    "key": "0x2"
+                }),
+                response: serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 0,
+                    "result": "0x999"
+                }),
+            },
+            RpcInteraction {
+                method: "starknet_blockNumber".to_string(),
+                params: serde_json::json!([]),
+                response: serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 1,
+                    "result": 100
+                }),
+            },
+        ],
+    };
+
+    let serialized = serde_json::to_string_pretty(&records).unwrap();
+    let deserialized: RpcRecords = serde_json::from_str(&serialized).unwrap();
+
+    assert_eq!(records.interactions.len(), deserialized.interactions.len());
+    assert_eq!(records.interactions[0].method, deserialized.interactions[0].method);
+    assert_eq!(records.interactions[0].params, deserialized.interactions[0].params);
+    assert_eq!(records.interactions[0].response, deserialized.interactions[0].response);
+}
+
+#[test]
+fn test_rpc_records_save_and_load() {
+    let records = RpcRecords {
+        interactions: vec![RpcInteraction {
+            method: "starknet_getNonce".to_string(),
+            params: serde_json::json!({"block_id": "latest", "contract_address": "0x1"}),
+            response: serde_json::json!({"jsonrpc": "2.0", "id": 0, "result": "0x0"}),
+        }],
+    };
+
+    let temp_dir = tempfile::tempdir().unwrap();
+    let path = temp_dir.path().join("test_record.json");
+
+    records.save(&path);
+    let loaded = RpcRecords::load(&path);
+
+    assert_eq!(loaded.interactions.len(), 1);
+    assert_eq!(loaded.interactions[0].method, "starknet_getNonce");
+}
+
+#[tokio::test]
+async fn test_mock_server_matches_rpc_request() {
+    let records = RpcRecords {
+        interactions: vec![RpcInteraction {
+            method: "starknet_blockNumber".to_string(),
+            params: serde_json::json!([]),
+            response: serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 0,
+                "result": 42
+            }),
+        }],
+    };
+
+    let server = setup_mock_rpc_server(&records).await;
+
+    // Send a JSON-RPC request with different id/jsonrpc version (should still match).
+    let client = reqwest::Client::new();
+    let response = client
+        .post(server.url())
+        .json(&serde_json::json!({
+            "jsonrpc": "2.0",
+            "id": 99,
+            "method": "starknet_blockNumber",
+            "params": []
+        }))
+        .send()
+        .await
+        .unwrap();
+
+    assert_eq!(response.status(), 200);
+    let body: serde_json::Value = response.json().await.unwrap();
+    assert_eq!(body["result"], 42);
+}