gnd: add mock IPFS client for file data source testing

Replaces the dummy IpfsRpcClient with a MockIpfsClient that serves
pre-loaded CID → bytes from a "files" array in test JSON files.
Missing CIDs are reported with a clear error instead of a 60-second
timeout. Also adds IpfsResponse::for_test() helper and documents the
unmocked eth_call timeout in the troubleshooting guide.

Author: dimitrovmaksim

gnd/docs/gnd-test.md

@@ -767,7 +767,7 @@ GraphQL queries → Assertions
 - **Real WASM runtime:** Uses `EthereumRuntimeAdapterBuilder` with real `ethereum.call` host function
 - **Pre-populated call cache:** `eth_call` responses are cached before indexing starts
 - **No IPFS for manifest:** Uses `FileLinkResolver` to load manifest/WASM from build directory
-- **Dummy RPC adapter:** Registered at `http://0.0.0.0:0` for capability lookup; never actually called
+- **Dummy RPC adapter:** Registered at `http://0.0.0.0:0` — exists so the runtime can resolve an adapter with the required capabilities. If a mapping makes an `ethereum.call` that has no matching mock in `ethCalls`, the call misses the cache and falls through to this dummy adapter. The connection is refused immediately (port 0 is invalid), which graph-node treats as a possible reorg and restarts the block stream. The indexer then loops until the 60-second test timeout. See [Unmocked eth_call](#unmocked-eth_call-causes-60-second-timeout) in Troubleshooting.
 
 ## Troubleshooting
 
@@ -799,6 +799,28 @@ GraphQL queries → Assertions
 2. Check function signature format: `"functionName(inputTypes)(returnTypes)"`
 3. Ensure parameters are in correct order
 
+### Unmocked eth_call Causes 60-Second Timeout
+
+**Cause:** A mapping handler calls `ethereum.call` (directly or via a generated contract binding) for a call that has no matching entry in `ethCalls`. The call misses the pre-populated cache and is forwarded to the dummy RPC adapter at `http://0.0.0.0:0`. The connection is refused immediately, but graph-node interprets connection errors as a possible chain reorganisation and restarts the block stream instead of failing. The indexer loops indefinitely until the test runner's 60-second timeout expires.
+
+**Symptom:** Test fails with `Sync timeout after 60s` with no indication of which call was missing.
+
+**Fix:**
+1. Add the missing call to `ethCalls` in your test block:
+   ```json
+   "ethCalls": [
+     {
+       "address": "0xContractAddress",
+       "function": "myFunction(uint256):(address)",
+       "params": ["42"],
+       "returns": ["0xSomeAddress"]
+     }
+   ]
+   ```
+2. If the call is not supposed to happen, check the mapping logic — a code path may be executing unexpectedly.
+
+**Known limitation:** There is currently no fail-fast error for unmocked calls. The only signal is the timeout. A future improvement will make the dummy adapter panic immediately on a cache miss with a descriptive message.
+
 ### Block Handler Not Firing
 
 **Cause:** Block handlers auto-fire, but might be outside data source's active range.

gnd/src/commands/test/mock_ipfs.rs

@@ -0,0 +1,46 @@
+//! Mock IPFS client for `gnd test`.
+//!
+//! Replaces the real `IpfsRpcClient` with a map of pre-loaded CID → bytes.
+//! Any CID not found in the map is sent to the `unresolved_tx` channel and
+//! an error is returned so the `OffchainMonitor` retries with backoff.
+//! After sync, the runner drains the channel and reports missing CIDs.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use graph::bytes::Bytes;
+use graph::ipfs::{
+    ContentPath, IpfsClient, IpfsError, IpfsMetrics, IpfsRequest, IpfsResponse, IpfsResult,
+};
+use tokio::sync::mpsc::UnboundedSender;
+
+pub struct MockIpfsClient {
+    pub files: HashMap<ContentPath, Bytes>,
+    pub metrics: IpfsMetrics,
+    pub unresolved_tx: UnboundedSender<ContentPath>,
+}
+
+#[async_trait]
+impl IpfsClient for MockIpfsClient {
+    fn metrics(&self) -> &IpfsMetrics {
+        &self.metrics
+    }
+
+    async fn call(self: Arc<Self>, req: IpfsRequest) -> IpfsResult<IpfsResponse> {
+        let path = match req {
+            IpfsRequest::Cat(p) | IpfsRequest::GetBlock(p) => p,
+        };
+
+        match self.files.get(&path) {
+            Some(bytes) => Ok(IpfsResponse::for_test(path, bytes.clone())),
+            None => {
+                let _ = self.unresolved_tx.send(path.clone());
+                Err(IpfsError::ContentNotAvailable {
+                    path,
+                    reason: anyhow::anyhow!("CID not found in mock 'files'"),
+                })
+            }
+        }
+    }
+}

gnd/src/commands/test/mod.rs

@@ -32,6 +32,7 @@ mod block_stream;
 mod eth_calls;
 mod matchstick;
 mod mock_chain;
+mod mock_ipfs;
 mod noop;
 mod output;
 mod runner;
@@ -170,7 +171,7 @@ pub async fn run_test(opt: TestOpt) -> Result<()> {
             }
         };
 
-        match runner::run_single_test(&opt, &manifest_info, &test_file).await {
+        match runner::run_single_test(&opt, &manifest_info, &test_file, &path).await {
             Ok(result) => {
                 output::print_test_result(&test_file.name, &result);
                 if result.is_passed() {

gnd/src/commands/test/runner.rs

@@ -13,6 +13,7 @@
 use super::assertion::run_assertions;
 use super::block_stream::StaticStreamBuilder;
 use super::mock_chain;
+use super::mock_ipfs::MockIpfsClient;
 use super::noop::{NoopAdapterSelector, StaticBlockRefetcher};
 use super::schema::{TestFile, TestResult};
 use super::trigger::build_blocks_with_triggers;
@@ -35,7 +36,7 @@ use graph::data::subgraph::schema::SubgraphError;
 use graph::endpoint::EndpointMetrics;
 use graph::env::EnvVars;
 use graph::firehose::{FirehoseEndpoint, FirehoseEndpoints, SubgraphLimit};
-use graph::ipfs::{IpfsMetrics, IpfsRpcClient, ServerAddress};
+use graph::ipfs::{ContentPath, IpfsMetrics};
 use graph::prelude::{
     DeploymentHash, LoggerFactory, NodeId, SubgraphCountMetric, SubgraphName, SubgraphRegistrar,
     SubgraphStore as SubgraphStoreTrait, SubgraphVersionSwitchingMode,
@@ -52,6 +53,7 @@ use graph_node::config::Config;
 use graph_node::manager::PanicSubscriptionManager;
 use graph_node::store_builder::StoreBuilder;
 use graph_store_postgres::{ChainHeadUpdateListener, ChainStore, Store, SubgraphStore};
+use std::collections::HashMap;
 use std::marker::PhantomData;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
@@ -256,6 +258,7 @@ pub async fn run_single_test(
     opt: &TestOpt,
     manifest_info: &ManifestInfo,
     test_file: &TestFile,
+    test_file_path: &Path,
 ) -> Result<TestResult> {
     // Warn (and short-circuit) when there are no assertions.
     if test_file.assertions.is_empty() {
@@ -286,6 +289,24 @@ pub async fn run_single_test(
         &manifest_info.receipt_required_selectors,
     )?;
 
+    // Build mock IPFS file map. Fails fast on invalid CIDs or unreadable file paths.
+    let test_file_dir = test_file_path
+        .parent()
+        .map(|p| p.to_path_buf())
+        .unwrap_or_else(|| PathBuf::from("."));
+
+    let mut mock_files: HashMap<ContentPath, graph::bytes::Bytes> = HashMap::new();
+    for entry in &test_file.files {
+        let path = ContentPath::new(&entry.cid)
+            .map_err(|e| anyhow!("Invalid CID '{}' in test files: {}", entry.cid, e))?;
+        let content = entry
+            .resolve(&test_file_dir)
+            .with_context(|| format!("Failed to resolve mock file for CID '{}'", entry.cid))?;
+        mock_files.insert(path, content);
+    }
+
+    let (unresolved_tx, mut unresolved_rx) = tokio::sync::mpsc::unbounded_channel::<ContentPath>();
+
     // Create the database for this test. For pgtemp, the `db` value must
     // stay alive for the duration of the test — dropping it destroys the database.
     let db = create_test_database(opt, &manifest_info.build_dir)?;
@@ -296,7 +317,15 @@ pub async fn run_single_test(
 
     let chain = setup_chain(&logger, blocks.clone(), &stores).await?;
 
-    let ctx = setup_context(&logger, &stores, &chain, manifest_info).await?;
+    let ctx = setup_context(
+        &logger,
+        &stores,
+        &chain,
+        manifest_info,
+        mock_files,
+        unresolved_tx,
+    )
+    .await?;
 
     // Populate eth_call cache with mock responses before starting indexer.
     // This ensures handlers can successfully retrieve mocked contract call results.
@@ -330,7 +359,34 @@ pub async fn run_single_test(
     )
     .await
     {
-        Ok(()) => run_assertions(&ctx, &test_file.assertions).await,
+        Ok(()) => {
+            // Drain any CIDs that were requested but not found in the mock.
+            // Deduplicate so each missing CID is listed once.
+            let mut unresolved: Vec<ContentPath> = Vec::new();
+            while let Ok(cid) = unresolved_rx.try_recv() {
+                if !unresolved.contains(&cid) {
+                    unresolved.push(cid);
+                }
+            }
+
+            if !unresolved.is_empty() {
+                let cid_list = unresolved
+                    .iter()
+                    .map(|p| format!("  - {}", p))
+                    .collect::<Vec<_>>()
+                    .join("\n");
+                Ok(TestResult {
+                    handler_error: Some(format!(
+                        "File data source requested CID not found in mock 'files':\n{}\n\
+                         Add the missing CID(s) to the \"files\" array in your test JSON.",
+                        cid_list
+                    )),
+                    assertions: vec![],
+                })
+            } else {
+                run_assertions(&ctx, &test_file.assertions).await
+            }
+        }
         Err(subgraph_error) => {
             // The subgraph handler threw a fatal error during indexing.
             // Report it as a test failure without running assertions.
@@ -614,6 +670,8 @@ async fn setup_context(
     stores: &TestStores,
     chain: &Arc<Chain>,
     manifest_info: &ManifestInfo,
+    mock_files: HashMap<ContentPath, graph::bytes::Bytes>,
+    unresolved_tx: tokio::sync::mpsc::UnboundedSender<ContentPath>,
 ) -> Result<TestContext> {
     let build_dir = &manifest_info.build_dir;
     let manifest_path = &manifest_info.manifest_path;
@@ -643,13 +701,14 @@ async fn setup_context(
         FileLinkResolver::new(Some(build_dir.to_path_buf()), aliases),
     );
 
-    // IPFS client is required by the instance manager constructor but not used
-    // for manifest loading (FileLinkResolver handles that).
+    // Replace the real IPFS client with a mock that serves pre-loaded content.
+    // FileLinkResolver handles manifest loading; the mock handles file data sources.
     let ipfs_metrics = IpfsMetrics::new(&mock_registry);
-    let ipfs_client = Arc::new(
-        IpfsRpcClient::new_unchecked(ServerAddress::test_rpc_api(), ipfs_metrics, logger)
-            .context("Failed to create IPFS client")?,
-    );
+    let ipfs_client = Arc::new(MockIpfsClient {
+        files: mock_files,
+        metrics: ipfs_metrics,
+        unresolved_tx,
+    });
 
     let ipfs_service = ipfs_service(
         ipfs_client,

gnd/src/commands/test/schema.rs

@@ -30,6 +30,7 @@
 //! }
 //! ```
 
+use graph::bytes::Bytes;
 use serde::Deserialize;
 use serde_json::Value;
 use std::path::{Path, PathBuf};
@@ -39,6 +40,10 @@ use std::path::{Path, PathBuf};
 pub struct TestFile {
     pub name: String,
 
+    /// Mock IPFS file contents keyed by CID. Used for file data sources.
+    #[serde(default)]
+    pub files: Vec<MockFile>,
+
     /// Ordered sequence of mock blocks to index.
     #[serde(default)]
     pub blocks: Vec<TestBlock>,
@@ -48,6 +53,64 @@ pub struct TestFile {
     pub assertions: Vec<Assertion>,
 }
 
+/// A mock IPFS file entry for file data source testing.
+///
+/// Exactly one of `content` or `file` must be set.
+#[derive(Debug, Clone, Deserialize)]
+pub struct MockFile {
+    /// Syntactically valid IPFS CID (v0 `Qm...` or v1 `bafy...`).
+    /// The CID does not need to be the actual hash of the content — the mock
+    /// ignores the hash relationship.
+    pub cid: String,
+
+    /// Inline UTF-8 content. Exactly one of `content` or `file` must be set.
+    #[serde(default)]
+    pub content: Option<String>,
+
+    /// Path to a file whose contents are loaded as UTF-8.
+    /// Resolved relative to the test JSON file. Exactly one of `content` or
+    /// `file` must be set.
+    #[serde(default)]
+    pub file: Option<String>,
+}
+
+impl MockFile {
+    /// Resolve this entry to bytes, given the directory of the test JSON file.
+    ///
+    /// Fails if:
+    /// - neither `content` nor `file` is set
+    /// - both `content` and `file` are set
+    /// - the referenced `file` path cannot be read
+    pub fn resolve(&self, test_dir: &Path) -> anyhow::Result<Bytes> {
+        match (&self.content, &self.file) {
+            (Some(content), None) => Ok(Bytes::from(content.clone().into_bytes())),
+            (None, Some(file)) => {
+                let path = if Path::new(file).is_absolute() {
+                    PathBuf::from(file)
+                } else {
+                    test_dir.join(file)
+                };
+                let data = std::fs::read(&path).map_err(|e| {
+                    anyhow::anyhow!("Failed to read file '{}': {}", path.display(), e)
+                })?;
+                Ok(Bytes::from(data))
+            }
+            (Some(_), Some(_)) => {
+                anyhow::bail!(
+                    "MockFile entry for CID '{}' must have either 'content' or 'file', not both",
+                    self.cid
+                )
+            }
+            (None, None) => {
+                anyhow::bail!(
+                    "MockFile entry for CID '{}' must have either 'content' or 'file'",
+                    self.cid
+                )
+            }
+        }
+    }
+}
+
 #[derive(Debug, Clone, Deserialize)]
 pub struct TestBlock {
     /// Block number. If omitted, auto-increments starting from `start_block`

graph/src/ipfs/client.rs

@@ -196,6 +196,16 @@ pub struct IpfsResponse {
 }
 
 impl IpfsResponse {
+    /// Construct an `IpfsResponse` from pre-buffered bytes.
+    ///
+    /// Intended for mock `IpfsClient` implementations in tests.
+    pub fn for_test(path: ContentPath, bytes: Bytes) -> Self {
+        Self {
+            path,
+            response: reqwest::Response::from(http::Response::new(bytes)),
+        }
+    }
+
     /// Reads and returns the response body.
     ///
     /// If the max size is specified and the response body is larger than the max size,