How to Run Tests for a Specific Crate in Macro: A Complete Guide

Use cargo test -p <crate-name> after starting services with bash .cursor/infra.sh and initializing the database with just setup_macrodb.

The Macro codebase is a Cargo workspace containing over 80 Rust crates. Testing individual components requires specific setup steps including PostgreSQL and Redis services. This guide covers the exact commands and prerequisites needed to run tests for a specific crate in the macro-inc/macro repository.

Prerequisites: Starting the Test Environment

Before executing tests for any crate, you must start the local infrastructure and prepare the database schema.

Launch Required Services with infra.sh

Many crates depend on PostgreSQL and Redis. The repository provides a helper script to start these services in Docker:

bash .cursor/infra.sh

This hidden script in .cursor/infra.sh brings up containers for Postgres, Redis, and other local dependencies required by the test suite.

Initialize the Database with Just Commands

The database schema lives in crates/macro_db_client/migrations/. Create and migrate the MacroDB using the provided Just recipe:

just setup_macrodb

Alternatively, you can run just initialize_dbs to achieve the same result. This command creates the database and runs all migrations defined in the migrations folder.

Running Tests for a Specific Crate

Once the environment is running, you can target individual crates using Cargo's workspace-aware commands.

Basic Test Command Syntax

Run all tests for a specific crate using the -p flag followed by the crate name as defined in its Cargo.toml:

cargo test -p agent_harness

Replace agent_harness with the target crate name. This pattern is used consistently throughout the repository's CI and development workflows.

Running Ignored Tests with Output

To run tests marked with #[ignore] and display println! output, append the following flags:

cargo test -p agent_harness -- --ignored --nocapture

• --ignored: Executes only tests marked with the ignore attribute.
• --nocapture: Shows standard output from test functions.

Executing a Single Test Function

Filter for a specific test by appending its name after the crate specification:

cargo test -p agent_harness test_message_routing

Cargo treats the argument after the crate name as a test filter, allowing you to run individual test functions without executing the entire suite.

Handling SQLx and Database Migrations

The project uses sqlx for type-checked SQL. Proper cache management is essential when database queries change.

Refresh sqlx Query Cache After Changes

If you modify SQL queries or apply new migrations, regenerate the offline query cache:

just prepare_db

Run this command only after changing queries or migrations to ensure the sqlx metadata stays synchronized with the actual database schema.

Critical: Avoid SQLX_OFFLINE Mode

According to CLAUDE.md in the repository root, do not set SQLX_OFFLINE=true when running tests. The project's testing guidelines explicitly require live database connections for integration tests. The offline mode is intended for builds only, not for test execution.

Summary

• Start services: Run bash .cursor/infra.sh to launch PostgreSQL and Redis containers.
• Prepare database: Execute just setup_macrodb to create the database and run migrations from crates/macro_db_client/migrations/.
• Run tests: Use cargo test -p <crate-name> to target specific crates in the workspace.
• Handle sqlx: Run just prepare_db after query changes, but never use SQLX_OFFLINE=true during testing.
• Filter tests: Append test names to run single functions, or use -- --ignored for ignored tests.

Frequently Asked Questions

Can I run tests for multiple crates at once?

Yes. You can run cargo test from the workspace root to test all crates, or use cargo test -p crate1 -p crate2 to target specific subsets. However, for isolated debugging, targeting a single crate with -p is the recommended approach.

Why do tests fail with database connection errors?

The test suite requires live PostgreSQL and Redis services. Ensure you ran bash .cursor/infra.sh to start Docker containers and just setup_macrodb to initialize the schema. Also verify that SQLX_OFFLINE is not set to true, as this prevents live database connections required by the test suite.

Where are the database migrations stored?

Migration files are located in crates/macro_db_client/migrations/. These SQL files define the schema used by many crates in the workspace. The just setup_macrodb command applies these migrations automatically.

How do I view print statements from my tests?

Add -- --nocapture to your cargo test command. For example: cargo test -p agent_harness -- --nocapture. This flag disables output capture, allowing you to see println! statements and other standard output from test functions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}