gnd(test): Add mock-based subgraph test runner

[dimitrovmaksim]

Summary

Implements a native test runner for gnd test that executes JSON-defined tests through real graph-node infrastructure (store, WASM runtime, trigger processing) with only the blockchain layer mocked. Provides a faster, integrated alternative to Matchstick while maintaining backward compatibility.

Key Features

• JSON test format - Define blocks, events, eth_calls, and GraphQL assertions
• Real graph-node pipeline - Tests run through actual indexing infrastructure
• Auto block triggers - All block handler filters work (once, polling, no filter)
• startBlock support - Auto-extracts from manifest and numbers blocks accordingly
• eth_call mocking - Pre-populate call cache before indexing
• Smart assertions - Order-insensitive comparison, type coercion, detailed diffs
• Database isolation - Fresh pgtemp database per test
• Backward compatible - --matchstick flag preserves legacy behavior

Architecture

JSON test → Parse → ABI encode events → StaticStreamBuilder (mock stream)
  → Real graph-node indexing (WASM + triggers + storage)
  → GraphQL assertions → Report results

Design decisions:

• Reuses actual graph-node stores, runtime, and trigger processing
• Only blockchain RPC is mocked (via StaticStreamBuilder)
• Fresh isolated database per test (pgtemp)
• Pre-populated eth_call cache for deterministic results

Usage

gnd test                    # Run all tests in tests/
gnd test tests/foo.json     # Run specific test
gnd test --skip-build       # Skip auto-build
gnd test --matchstick       # Legacy Matchstick mode
gnd test --help             # To see usage and all options 

Test Format Example

{
  "name": "Transfer creates entity",
  "blocks": [
    {
      "number": 1,
      "events": [
        {
          "address": "0x1234...",
          "event": "Transfer(address indexed from, address indexed to, uint256 value)",
          "params": {"from": "0xaaaa...", "to": "0xbbbb...", "value": "1000"}
        }
      ],
      "ethCalls": [
        {
          "address": "0x1234...",
          "function": "balanceOf(address)(uint256)",
          "params": ["0xaaaa..."],
          "returns": ["1000000000000000000"]
        }
      ]
    }
  ],
  "assertions": [
    {
      "query": "{ transfer(id: \"1\") { from to value } }",
      "expected": {"transfer": {"from": "0xaaaa...", "to": "0xbbbb...", "value": "1000"}}
    }
  ]
}

Implementation

Modified Graph-Node Files

• graph/src/data_source/subgraph.rs - Minor exports for startBlock support

Supported Features

Feature	Status
Log events	✅ Supported
Block handlers (once, polling, no filter)	✅ Supported
eth_call mocking	✅ Supported
Dynamic/template data sources	⚠️ Not Tested
Transaction receipts	❌ Not implemented
File data sources / IPFS	❌ Not implemented
Call triggers (traces)	❌ Not implemented

Breaking Changes

None. Adds native testing while preserving --matchstick for backward compatibility.

Code Attribution

⚠️ Almost all implementation code was generated by Claude Code through investigation of graph-node's indexing pipeline, existing test infrastructure, and iterative design refinement.

Human contributions: Initial requirements, code review, validation, and bug fixes.

Future Work

• Configurable timeout (env var or CLI flag)
• Multi-datasource startBlock warning
• Test validation (block ordering, address format)
• --json CI output format
• Parallel test execution
• Test filtering (--filter)

Checklist

• Implementation complete
• User documentation (776-line README)
• Backward compatible via --matchstick
• Validated with real subgraphs
• All block handler filters supported
• startBlock handling working
• No breaking changes