> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Guide

> Comprehensive guide to testing Graph Node including unit tests, runner tests, and integration tests

Graph Node has a comprehensive test suite covering unit tests, runner tests (integration-style tests), and full integration tests. This guide explains how to run each type of test and when to use them.

<Note>
  Use unit tests for regular development. Only run integration tests when explicitly needed or when making changes to integration/end-to-end functionality.
</Note>

## Test Types Overview

Graph Node uses three types of tests:

1. **Unit Tests**: Fast, focused tests inlined with source code
2. **Runner Tests**: Medium-speed integration-style tests for subgraph execution
3. **Integration Tests**: Full end-to-end tests with real services

## Unit Tests

Unit tests are inlined with the source code and test individual functions and modules in isolation.

### Prerequisites

<Steps>
  <Step title="Start PostgreSQL">
    PostgreSQL must be running on `localhost:5432` with an initialized `graph-test` database.

    Using Process Compose (recommended):

    ```bash theme={null}
    nix run .#unit
    ```

    Or manually:

    ```bash theme={null}
    psql -U postgres <<EOF
    create user graph with password 'graph';
    create database "graph-test" with owner=graph template=template0 encoding='UTF8' locale='C';
    create extension pg_trgm;
    create extension btree_gist;
    create extension postgres_fdw;
    EOF
    ```
  </Step>

  <Step title="Start IPFS">
    IPFS must be running on `localhost:5001`.

    ```bash theme={null}
    ipfs daemon
    ```
  </Step>

  <Step title="Install Additional Tools">
    Install PNPM and Foundry:

    ```bash theme={null}
    # PNPM
    npm install -g pnpm

    # Foundry (for smart contract compilation)
    curl -L https://foundry.paradigm.xyz | bash
    foundryup
    ```
  </Step>

  <Step title="Set Environment Variable">
    ```bash theme={null}
    export THEGRAPH_STORE_POSTGRES_DIESEL_URL=postgresql://graph:graph@127.0.0.1:5432/graph-test
    ```
  </Step>
</Steps>

### Running Unit Tests

<CodeGroup>
  ```bash All Tests theme={null}
  # Run all unit tests
  just test-unit
  ```

  ```bash Specific Tests theme={null}
  # Run specific test module (e.g., data_source::common::tests)
  just test-unit data_source::common::tests
  ```

  ```bash With Output theme={null}
  # Run with verbose output
  just test-unit -- --nocapture
  ```
</CodeGroup>

<Warning>
  **Test Verification Requirement**: When filtering for specific tests, ensure the intended test name(s) appear in the output. Cargo can exit successfully even when no tests matched your filter.
</Warning>

### Unit Test Best Practices

* Write unit tests for all new functions and modules
* Keep tests focused on a single behavior
* Use descriptive test names that explain what is being tested
* Mock external dependencies when possible
* Tests should be fast (\< 1 second each)

## Runner Tests

Runner tests are integration-style tests that test subgraph execution with real services but in a controlled environment.

### Prerequisites

Runner tests use the same prerequisites as unit tests:

1. PostgreSQL running on `localhost:5432` (with initialized `graph-test` database)
2. IPFS running on `localhost:5001`
3. PNPM installed
4. Foundry installed
5. Environment variable `THEGRAPH_STORE_POSTGRES_DIESEL_URL` set

<Note>
  Runner tests use the same Nix services stack as unit tests:

  ```bash theme={null}
  nix run .#unit
  ```
</Note>

### Running Runner Tests

<CodeGroup>
  ```bash All Tests theme={null}
  # Run all runner tests
  just test-runner
  ```

  ```bash Specific Tests theme={null}
  # Run specific test (e.g., block_handlers)
  just test-runner block_handlers
  ```
</CodeGroup>

### Runner Test Characteristics

* Take moderate time (10-20 seconds)
* Automatically reset the database between runs
* Some tests can pass without IPFS, but tests involving file data sources require it
* Test real subgraph execution with compiled WASM

<Warning>
  **Test Verification Requirement**: When filtering for specific tests, ensure the intended test name(s) appear in the output.
</Warning>

## Integration Tests

<Warning>
  **Only run integration tests when explicitly needed:**

  * Making changes to integration/end-to-end functionality
  * Debugging issues requiring full system testing
  * Preparing releases or major changes

  Integration tests take several minutes to complete.
</Warning>

Integration tests run Graph Node with real blockchain nodes and test the complete indexing pipeline.

### Prerequisites

<Steps>
  <Step title="Start PostgreSQL">
    PostgreSQL must be running on `localhost:3011` with an initialized `graph-node` database.

    Using Process Compose (recommended):

    ```bash theme={null}
    nix run .#integration
    ```
  </Step>

  <Step title="Start IPFS">
    IPFS must be running on `localhost:3001`.

    Included in Process Compose setup above.
  </Step>

  <Step title="Start Anvil">
    Anvil (Ethereum test chain) must be running on `localhost:3021`.

    Included in Process Compose setup above.
  </Step>

  <Step title="Install Tools">
    Install PNPM and Foundry as described in the unit tests section.
  </Step>
</Steps>

### Running Integration Tests

<CodeGroup>
  ```bash All Tests theme={null}
  # Run all integration tests
  # Automatically builds graph-node and gnd
  just test-integration
  ```

  ```bash Specific Test Case theme={null}
  # Run a specific integration test case (e.g., "grafted")
  TEST_CASE=grafted just test-integration
  ```

  ```bash With Graph CLI theme={null}
  # Use graph-cli instead of gnd for compatibility testing
  GRAPH_CLI=node_modules/.bin/graph just test-integration
  ```
</CodeGroup>

### Integration Test Verification

<Warning>
  **Critical Verification Requirements:**

  * **ALWAYS verify tests actually ran**: Check the output for "test result: ok. X passed" where X > 0
  * **If output shows "0 passed" or "0 tests run"**: The TEST\_CASE variable or filter was wrong - fix and re-run
  * **Never trust exit code 0 alone**: Cargo can exit successfully even when no tests matched your filter
</Warning>

### Integration Test Logs

Logs are written to `tests/integration-tests/graph-node.log` for debugging:

```bash theme={null}
# View logs during test run
tail -f tests/integration-tests/graph-node.log

# Search for errors
grep ERROR tests/integration-tests/graph-node.log
```

## Service Configuration

### Port Mapping

| Service          | Unit Tests Port | Integration Tests Port | Database/Config                                 |
| ---------------- | --------------- | ---------------------- | ----------------------------------------------- |
| PostgreSQL       | 5432            | 3011                   | `graph-test` / `graph-node`                     |
| IPFS             | 5001            | 3001                   | Data in `./.data/unit` or `./.data/integration` |
| Anvil (Ethereum) | -               | 3021                   | Deterministic test chain                        |

### Process Compose Services

The repository includes Process Compose configurations for managing test services:

<CodeGroup>
  ```bash Unit/Runner Tests theme={null}
  # Start PostgreSQL + IPFS for unit/runner tests
  nix run .#unit
  ```

  ```bash Integration Tests theme={null}
  # Start PostgreSQL + IPFS + Anvil for integration tests
  nix run .#integration
  ```
</CodeGroup>

## Code Quality Checks

<Warning>
  **Mandatory before ANY commit:**

  * `cargo fmt --all` MUST be run
  * `just lint` MUST show zero warnings
  * `cargo check --release` MUST complete successfully
  * Unit test suite MUST pass
</Warning>

### Running Quality Checks

<Steps>
  <Step title="Format Code">
    ```bash theme={null}
    # 🚨 MANDATORY: Format all code after any .rs file edit
    just format
    ```
  </Step>

  <Step title="Lint Code">
    ```bash theme={null}
    # 🚨 MANDATORY: Check for warnings and errors
    just lint
    ```

    This must show **zero warnings** before committing.
  </Step>

  <Step title="Check Release Build">
    ```bash theme={null}
    # 🚨 MANDATORY: Catch linking/optimization issues
    just check --release
    ```

    This catches issues that `cargo check` alone might miss.
  </Step>

  <Step title="Run Tests">
    ```bash theme={null}
    # 🚨 MANDATORY: Ensure tests pass
    just test-unit
    ```
  </Step>
</Steps>

## Development Workflow

### Continuous Testing During Development

Use `cargo-watch` to automatically run checks during development:

```bash theme={null}
# Install cargo-watch
cargo install cargo-watch

# Run continuous testing
cargo watch \
    -x "fmt --all" \
    -x check \
    -x "test -- --test-threads=1" \
    -x "doc --no-deps"
```

This will continuously:

1. Format all source files
2. Check for compilation errors
3. Run tests
4. Generate documentation

### Test-Driven Development

<Steps>
  <Step title="Write Test First">
    Write a failing test that describes the desired behavior:

    ```rust theme={null}
    #[test]
    fn test_new_feature() {
        let result = new_feature();
        assert_eq!(result, expected_value);
    }
    ```
  </Step>

  <Step title="Run Test to Verify Failure">
    ```bash theme={null}
    just test-unit new_feature
    ```
  </Step>

  <Step title="Implement Feature">
    Write the minimum code needed to make the test pass.
  </Step>

  <Step title="Run Test to Verify Success">
    ```bash theme={null}
    just test-unit new_feature
    ```
  </Step>

  <Step title="Run All Quality Checks">
    ```bash theme={null}
    just format
    just lint
    just check --release
    just test-unit
    ```
  </Step>
</Steps>

## Testing Specific Components

### Testing Store Changes

<CodeGroup>
  ```bash Store Tests theme={null}
  # Test store-related functionality
  just test-unit store::
  ```

  ```bash Diesel Tests theme={null}
  # Test database queries
  just test-unit diesel::
  ```
</CodeGroup>

### Testing Chain Adapters

<CodeGroup>
  ```bash Ethereum Tests theme={null}
  # Test Ethereum chain adapter
  just test-unit ethereum::
  ```

  ```bash NEAR Tests theme={null}
  # Test NEAR chain adapter
  just test-unit near::
  ```
</CodeGroup>

### Testing GraphQL

<CodeGroup>
  ```bash GraphQL Tests theme={null}
  # Test GraphQL query execution
  just test-unit graphql::
  ```

  ```bash Schema Tests theme={null}
  # Test GraphQL schema generation
  just test-unit schema::
  ```
</CodeGroup>

## Debugging Tests

### View Test Output

```bash theme={null}
# Show println! and dbg! output
just test-unit test_name -- --nocapture

# Show detailed test information
just test-unit test_name -- --show-output
```

### Run Tests in Serial

```bash theme={null}
# Run tests one at a time (useful for database tests)
just test-unit -- --test-threads=1
```

### Debug with RUST\_LOG

```bash theme={null}
# Enable debug logging
RUST_LOG=debug just test-unit test_name

# Enable trace logging for specific module
RUST_LOG=graph::store=trace just test-unit test_name
```

## Common Test Issues

### Database Connection Errors

<Warning>
  If you see database connection errors, ensure:

  * PostgreSQL is running on the correct port
  * The database exists and has the required extensions
  * The `THEGRAPH_STORE_POSTGRES_DIESEL_URL` environment variable is set correctly
</Warning>

```bash theme={null}
# Verify database connection
psql $THEGRAPH_STORE_POSTGRES_DIESEL_URL -c "SELECT 1;"
```

### IPFS Connection Errors

<Warning>
  If you see IPFS errors:

  * Ensure IPFS daemon is running: `ipfs daemon`
  * Check IPFS is accessible: `curl http://localhost:5001/api/v0/version`
</Warning>

### Test Timeout Issues

```bash theme={null}
# Increase test timeout
just test-unit test_name -- --test-threads=1 --timeout=300
```

## Best Practices

<Steps>
  <Step title="Write Tests First">
    Use test-driven development: write tests before implementation.
  </Step>

  <Step title="Keep Tests Fast">
    Unit tests should be fast. Move slow tests to runner or integration tests.
  </Step>

  <Step title="Test Edge Cases">
    Test boundary conditions, error cases, and unusual inputs.
  </Step>

  <Step title="Use Descriptive Names">
    Test names should clearly describe what is being tested.
  </Step>

  <Step title="Clean Up Resources">
    Ensure tests clean up after themselves (database, files, etc.).
  </Step>

  <Step title="Verify Test Coverage">
    Use `cargo tarpaulin` or similar tools to check test coverage.
  </Step>
</Steps>

## Resources

* [Rust Testing Documentation](https://doc.rust-lang.org/book/ch11-00-testing.html)
* [Cargo Test Documentation](https://doc.rust-lang.org/cargo/commands/cargo-test.html)
* [Graph Node Repository](https://github.com/graphprotocol/graph-node)
* [Contributing Guide](/development/contributing)