Code Testing Skill

This skill provides testing operations for the project codebase using cargo-nextest (preferred) or cargo test (fallback).

When to Use This Skill

Use this skill when you need to:

•Run tests after implementing features or fixing bugs
•Validate that changes don't break existing functionality
•Run specific test suites (unit, integration, local-only)
•Test specific packages

Available Commands

Run Local Tests Only (RECOMMENDED FOR LOCAL DEVELOPMENT)

bash

just test-local [EXTRA_FLAGS]

Runs only tests that don't require external dependencies using the "local" nextest profile. Uses cargo nextest run --profile local --workspace.

Requires: cargo-nextest must be installed (this command will fail without it).

Use this when: Working locally without access to external services (databases, Firehose endpoints, etc.).

This is the PRIMARY testing command for local development.

Examples:

•just test-local - run all local tests

Run All Tests (REQUIRES EXTERNAL DEPENDENCIES)

bash

just test [EXTRA_FLAGS]

Runs all tests (unit and integration) in the workspace. Uses cargo nextest run --workspace if nextest is available, otherwise falls back to cargo test --workspace.

⚠️ WARNING: This command requires external dependencies (PostgreSQL, Firehose services, etc.) that may not be available locally.

Use this when: Running in CI or when you have all external services configured.

Examples:

•just test - run all tests
•just test -- --nocapture - run with output capture disabled
•just test my_test_name - run specific test by name

Run Unit Tests Only (REQUIRES EXTERNAL DEPENDENCIES)

bash

just test-unit [EXTRA_FLAGS]

Runs only unit tests, excluding integration tests and ampup package. Uses cargo nextest run --workspace --exclude tests --exclude ampup.

⚠️ WARNING: Some unit tests may require external dependencies (e.g., PostgreSQL for metadata-db tests).

Use this when: You want faster feedback than full test suite, but slower than test-local.

Examples:

•just test-unit - run all unit tests
•just test-unit -p metadata-db - run unit tests for metadata-db crate

Run Integration Tests (REQUIRES EXTERNAL DEPENDENCIES)

bash

just test-it [EXTRA_FLAGS]

Runs integration tests from the tests package. Uses cargo nextest run --package tests.

⚠️ WARNING: Integration tests require external dependencies (databases, Firehose endpoints, etc.).

Use this when: You need to validate end-to-end functionality and have external services available.

Examples:

•just test-it - run all integration tests
•just test-it test_name - run specific integration test

Run Ampup Tests (REQUIRES EXTERNAL DEPENDENCIES)

bash

just test-ampup [EXTRA_FLAGS]

Runs tests for the ampup package. Uses cargo nextest run --package ampup.

⚠️ WARNING: May require external dependencies.

Examples:

•just test-ampup - run ampup tests

Important Guidelines

Cargo Nextest vs Cargo Test

The project prefers cargo-nextest for faster test execution:

•Nextest runs tests in parallel more efficiently
•Better output formatting and filtering
•Install with: cargo install --locked cargo-nextest@^0.9

All test commands automatically detect nextest availability:

•If nextest is installed: uses it automatically
•If not installed: falls back to cargo test with a warning

Pre-approved Commands

This test command is pre-approved and can be run without user permission:

•just test-local - The ONLY test command that should be used for local development

Test Workflow Recommendations

•During local development: ALWAYS use just test-local - it's designed to work without external dependencies
•Before commits (local): Run just test-local to validate changes
•In CI environments: The CI system will run just test or other commands with proper service configurations
•DO NOT run locally: just test, just test-unit, just test-it, or just test-ampup unless you have explicitly configured all external services

External Dependencies Required by Non-Local Tests

The following tests require external services that are typically not available in local development:

•PostgreSQL database: Required for metadata-db tests
•Firehose endpoints: Required for Firehose dataset tests
•EVM RPC endpoints: Required for EVM RPC dataset tests
•Other services: As configured in docker-compose or CI environment

Use just test-local to avoid these dependencies during local development.

Common Test Flags

You can pass extra flags to cargo through the EXTRA_FLAGS parameter:

•-p <package> or --package <package> - test specific package
•test_name - run tests matching name
•-- --nocapture - show println! output (cargo test only)
•-- --show-output - show output from passing tests (nextest)

Common Mistakes to Avoid

❌ Anti-patterns

•Never run cargo test directly - Use justfile tasks for proper configuration
•Never run just test locally - It requires external dependencies
•Never skip tests - Even for "trivial" changes
•Never ignore failing tests - Fix them or document why they fail
•Never run integration tests locally - Use just test-local instead

✅ Best Practices

•Always use just test-local for local development
•Run tests after EVERY code change
•Fix failing tests immediately
•If nextest not installed, install it for better performance
•Run tests before commits

Validation Loop Pattern

code

Code Change → Format → Check → Clippy → Test
                ↑                          ↓
                ←── Fix failures ──────────┘

If tests fail:

•Read error messages carefully
•Fix the issue
•Format the fix (just fmt-file)
•Check compilation (just check-crate)
•Re-run tests (just test-local)
•Repeat until all pass

Next Steps

After all tests pass:

•Generate schemas if needed → See .claude/skills/code-gen/SKILL.md
•Review changes → Ensure quality before commits
•Commit → All checks and tests must be green

Project Context

•This is a Rust workspace with multiple crates
•Integration tests are in the tests/ package
•Some tests require external dependencies (databases, services)
•Test configurations are defined in .config/nextest.toml
•Nextest profiles: default and local