Matchstick excels at providing a native, purpose-built environment for subgraph unit and integration testing because it runs in a deterministic WebAssembly (WASM) runtime that mimics The Graph's hosted service. For example, it allows you to mock events and call handlers directly, offering sub-millisecond test execution times for rapid iteration. Its tight integration with the Graph CLI (graph test) and support for fixtures makes it the de facto standard for teams building on The Graph's canonical stack, such as Uniswap or Balancer.
LABS
Comparisons
Subgraph Testing with Matchstick vs Custom Hardhat Scripts
A technical analysis comparing The Graph's purpose-built Matchstick framework against general-purpose Hardhat scripts for validating subgraph logic, data integrity, and event handling.
Chainscore © 2026
introduction
THE ANALYSIS
Introduction: The Core Testing Dilemma for Subgraph Developers
Choosing the right testing framework for your subgraph development is a critical infrastructure decision that impacts developer velocity and deployment confidence.
Custom Hardhat Scripts take a different approach by leveraging a full EVM development environment. This strategy results in the trade-off of higher fidelity—testing against a forked mainnet or local node—at the cost of setup complexity and slower execution times (tests can take seconds to minutes). This approach is favored by protocols like Aave, which use Hardhat's robust plugin ecosystem to test complex, stateful logic that depends on real blockchain interactions and contract deployments.
The key trade-off: If your priority is developer speed and a standardized workflow tightly coupled with The Graph's toolchain, choose Matchstick. If you prioritize end-to-end fidelity and testing subgraphs within a broader smart contract CI/CD pipeline, choose Custom Hardhat Scripts.
tldr-summary
Matchstick vs. Hardhat Scripts
TL;DR: Key Differentiators at a Glance
A direct comparison of the specialized Subgraph testing framework versus a general-purpose blockchain development tool.
02
Matchstick: Declarative Testing Model
Entity-centric assertions: Tests are written by defining the expected state of the store after events are processed, not by mocking low-level calls. This aligns with the declarative nature of Subgraphs and reduces boilerplate. This matters for developers who want to test what the Subgraph saves, not how it runs.
04
Custom Hardhat Scripts: Toolchain Flexibility
Leverage existing stack: Use Hardhat plugins (Waffle, Ethers), custom tasks, and your mainnet forking setup. This avoids context switching and allows you to reuse deployment & seeding logic. This matters for teams already deep in the Hardhat ecosystem who need to add Subgraph tests to their existing workflow.
05
Matchstick: Limited Chain Context
No live chain interaction: It's a unit testing framework, not an integration test suite. You cannot test contract deployments, transaction ordering, or gas-dependent logic. This is a trade-off for speed and isolation, but a weakness for testing the on-chain triggers themselves.
06
Hardhat Scripts: Higher Maintenance Burden
Manual orchestration required: You must write scripts to spin up a node, deploy contracts, run the Graph Node, and coordinate the indexing process. This creates fragile, slower tests compared to Matchstick's instant unit tests. This is a trade-off for the added integration fidelity.
HEAD-TO-HEAD COMPARISON FOR SUBGRAPH TESTING
Feature Matrix: Matchstick vs Hardhat Scripts
Direct comparison of testing frameworks for The Graph subgraph development.
| Metric / Feature | Matchstick (Subgraph) | Hardhat Scripts (Custom) |
|---|---|---|
Purpose-Built for Subgraphs | ||
Assertion Library for Events & Calls | ||
Mock Smart Contract State | ||
Test Execution Speed | < 2 sec (in-memory) | ~10-30 sec (forked chain) |
Native GraphQL Response Testing | ||
Requires Running Local Node | ||
Integration with Hardhat Workflow | via plugin | native |
pros-cons-a
Subgraph Testing Framework Comparison
Matchstick vs. Custom Hardhat Scripts
Key strengths and trade-offs for testing The Graph subgraphs, helping CTOs and protocol architects choose the right tool for their stack.
01
Matchstick: Subgraph-Native Testing
Purpose-built for The Graph: Directly integrates with the Graph CLI and AssemblyScript runtime. This matters for unit and integration testing of mappings and entities with deterministic mock data.
- Native Entity Handling: Automatically manages
store.get,store.set, andBytesIDs. - Deterministic Mocking: Uses
createMockedFunctionandassert.*helpers for reliable, repeatable tests. - Best for: Teams whose primary output is a production subgraph and need to test logic in isolation.
02
Matchstick: Development Velocity
Rapid iteration with a focused toolchain. The graph test command provides a fast feedback loop, compiling and running tests in a dedicated environment.
- Quick Setup: Minimal configuration needed if already using Graph CLI.
- Integrated Debugging: Clear error traces point directly to mapping logic.
- Trade-off: Less flexible for testing complex, multi-contract interactions that require a full local blockchain.
03
Custom Hardhat Scripts: Full-Stack Flexibility
End-to-end testing in a live EVM environment. Deploy real contracts to a local Hardhat Network, emit events, and test the subgraph's indexing against a real node.
- Real-World Simulation: Tests the entire flow from transaction → event → subgraph handler.
- Toolchain Integration: Leverage Hardhat plugins (e.g.,
@nomicfoundation/hardhat-ethers) for advanced fixture management and contract interaction. - Best for: Protocols with complex business logic where the subgraph must be validated against actual contract state changes.
04
Custom Hardhat Scripts: Ecosystem & Control
Leverage the mature Ethereum development ecosystem. Use established testing patterns (Mocha/Chai, Waffle), CI/CD integrations, and custom utilities.
- Maximum Control: Script and orchestrate any pre- or post-indexing logic.
- Broader Testing: Can test subgraph as one component within a larger protocol test suite.
- Trade-off: Requires significant boilerplate to mock The Graph's store interface and manage test data lifecycle, increasing maintenance overhead.
pros-cons-b
Subgraph Testing with Matchstick vs Custom Hardhat Scripts
Custom Hardhat Scripts: Pros and Cons
Key strengths and trade-offs for testing The Graph subgraphs at a glance.
01
Matchstick: Native Subgraph Environment
Purpose-built framework: Provides a testing environment that mirrors The Graph's AssemblyScript runtime. This matters for catching runtime-specific errors (e.g., store.get(), BigInt handling) that a generic EVM script would miss. Use it for unit and integration tests of mapping logic.
02
Matchstick: Deterministic Mock Data
Integrated mocking utilities: Includes createMockedFunction, assert.*, and newMockEvent for generating predictable test fixtures. This matters for ensuring reproducible test runs and CI/CD pipeline stability. Avoids flaky tests from on-chain RPC variability.
03
Custom Hardhat Scripts: Full-Stack Integration
End-to-end workflow control: Deploy contracts, simulate transactions, and index them in a single script using Hardhat's Ethers.js and network providers. This matters for testing the entire data pipeline from contract event to subgraph entity, catching integration gaps.
04
Custom Hardhat Scripts: Leverage Existing Tooling
Reuse dev environment: Utilize your project's existing Hardhat config, deployment scripts, and TypeChain types. This matters for developer efficiency and consistency, avoiding context switching between a Subgraph project and your core protocol repo.
05
Matchstick: Limited to Subgraph Scope
Cannot test on-chain state: Matchstick tests run in an isolated VM, disconnected from a live blockchain node. This is a critical weakness for validating that your subgraph correctly interprets complex, multi-contract transaction logs from a real fork.
06
Custom Hardhat Scripts: Higher Maintenance Burden
Manual fixture management: You must write boilerplate to sync contract state, trigger events, and wait for indexing. This matters for team scalability as test suites grow, increasing the risk of brittle, slow tests compared to Matchstick's declarative mocks.
CHOOSE YOUR PRIORITY
Decision Framework: When to Choose Which Tool
Matchstick for Speed & DX
Verdict: The clear winner for rapid iteration. Strengths:
- Fast Feedback: In-memory unit tests execute in milliseconds, enabling a true TDD workflow.
- Integrated Tooling: Native
graph testcommand with automatic fixture loading and mock generation. - Declarative Testing: Write tests in a domain-specific language (AssemblyScript/TypeScript) that mirrors Subgraph mappings, reducing cognitive load. Use When: You need to validate mapping logic quickly during active development of a new subgraph for protocols like Uniswap V3 or Aave.
Custom Hardhat Scripts for Speed & DX
Verdict: Slower feedback loop, but offers deeper integration. Strengths:
- Single Environment: If your core contracts are already tested with Hardhat, you can reuse the same setup and deployment scripts.
- Full EVM Fidelity: Tests run against a forked mainnet or local node (e.g., Anvil), capturing edge cases in contract interactions. Trade-off: Spinning up a node and deploying contracts for each test run is orders of magnitude slower than Matchstick's in-memory approach.
verdict
THE ANALYSIS
Final Verdict and Strategic Recommendation
Choosing the right Subgraph testing tool depends on your team's workflow, technical debt tolerance, and the complexity of your data transformations.
Matchstick excels at providing a specialized, end-to-end testing environment for Subgraphs because it is purpose-built by The Graph Foundation. It offers native integration with the Graph CLI, a dedicated assemblyscript runtime, and the ability to mock smart contract calls and event data. For example, its createMockedFunction and assert.fieldEquals utilities allow developers to write deterministic unit and integration tests that mirror the actual indexer environment, significantly reducing the risk of on-chain integration failures.
Custom Hardhat Scripts take a different approach by leveraging a mature, general-purpose development framework. This strategy results in a trade-off: you gain access to Hardhat's superior local blockchain forking, comprehensive debugging tools, and seamless integration with your existing Solidity contract test suite, but you must manually orchestrate the Subgraph deployment and indexing lifecycle, which can lead to brittle, project-specific test harnesses.
The key trade-off: If your priority is developer experience and Subgraph-specific fidelity, choose Matchstick. Its dedicated tooling and official support streamline the testing of complex event handlers and data mappings. If you prioritize integration with a broader Web3 stack and advanced local chain simulation, choose Custom Hardhat Scripts. This is ideal for teams already deep in the Hardhat ecosystem who need to test intricate interactions between their smart contracts and the Subgraph in a single, unified environment.
ENQUIRY
Get In Touch
today.
Our experts will offer a free quote and a 30min call to discuss your project.
NDA Protected
Confidentiality24h Response
Time to ValueDirectly to Engineering Team
No Sales Fluff10+
Protocols Shipped
$20M+
TVL Overall