How to Run Tests in the Macro Repository: A Complete Guide

Run tests in the macro repository by entering a Nix development shell, starting Docker-based services with just run_local, and invoking just test or cargo test -p <crate> after preparing the database environment.

This guide covers the exact workflow used by the macro-inc/macro codebase, a Rust workspace that relies on PostgreSQL, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth forintegration testing. Follow these steps to execute the full test suite or target specific crates.

---

Prerequisites for Running Tests

The macro repository requires two tools for local development and testing:

• Nix — provides the reproducible development shell containing just, Cargo, SQLx, Zig, and the Rust toolchain
• Docker Compose v2 — supplies the containerized services that integration tests depend on

Install Nix from nix.dev/install-nix and Docker from docs.docker.com/get-docker. These are the only required tools according to docs/RUNNING_LOCALLY.md【/cache/repos/github.com/macro-inc/macro/main/docs/RUNNING_LOCALLY.md#L07-L11】.

---

Enter the Nix Development Shell

Clone the repository and enter the Nix shell to load all development dependencies:

git clone https://github.com/macro-inc/macro.git
cd macro
nix develop

If Nix reports an "experimental features" error, enable flakes for that invocation:

nix develop --extra-experimental-features nix-command \
            --extra-experimental-features flakes

This workflow is documented in docs/RUNNING_LOCALLY.md【/cache/repos/github.com/macro-inc/macro/main/docs/RUNNING_LOCALLY.md#L21-L31】.

---

Start the Required Services

Integration tests in the macro repository communicate with real service instances. You have two options for starting these services.

Option A: Minimal Setup (PostgreSQL Only)

Most crate tests only require PostgreSQL:

docker compose -f docker/docker-compose.yml up -d postgres

Option B: Full Stack (End-to-End Tests)

Run the complete service stack for comprehensive integration testing:

just run_local --no-doppler

The --no-doppler flag boots all services without requiring Doppler secrets management. This matches the testing workflow described in CLAUDE.md【/cache/repos/github.com/macro-inc/macro/main/CLAUDE.md#L80-L86】.

---

Prepare the Test Environment

Before executing any tests, you must complete three setup steps:

just setup_test_envs    # Generate .env files for test configuration

just initialize_dbs     # Run database migrations for all services

just prepare_db         # Refresh the SQLx query cache

These commands are explicitly required by CLAUDE.md【/cache/repos/github.com/macro-inc/macro/main/CLAUDE.md#L81-L86】 and CONTRIBUTING.md【/cache/repos/github.com/macro-inc/macro/main/CONTRIBUTING.md#L50-L55】. The SQLx cache preparation ensures compiled queries match your current database schema.

Critical: Disable SQLx Offline Mode

Never set SQLX_OFFLINE=true when running cargo test. This environment variable is reserved for cargo check, cargo build, and cargo clippy only. Tests require a live PostgreSQL connection to verify query correctness【/cache/repos/github.com/macro-inc/macro/main/CLAUDE.md#L48-L52】.

---

Execute the Test Suite

Once services are running and the environment is prepared, choose your test execution method.

Run All Workspace Tests

just test

This command walks the workspace Cargo.toml and executes tests for all 80+ member crates.

Target a Specific Crate

cargo test -p document_storage_service

Replace document_storage_service with any crate name from the workspace. This approach is recommended in CONTRIBUTING.md for verifying changes to specific components.

Run End-to-End Integration Tests

Some crates include dedicated e2e test suites under crates/integration_tests:

nix develop --command cargo test -p local_e2e_integration_tests \
            --test bot_entity_access -- --ignored --nocapture

Crate-specific test commands with additional flags (such as --target wasm32-unknown-unknown) appear in individual README files like crates/client/turso-opfs/README.md【/cache/repos/github.com/macro-inc/macro/main/crates/client/turso-opfs/README.md#L35-L59】.

---

Troubleshooting Test Failures

If tests fail with "no cached data" errors, refresh the SQLx cache and retry:

just prepare_db --tests   # Include --tests flag for test-code cache issues

cargo test -p <crate>

Verify success with output similar to:

test result: ok. 123 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

---

Complete Test Workflow Example

Execute the full setup and test run in one sequence:

nix develop && \
just setup_test_envs && \
just initialize_dbs && \
just prepare_db && \
just test

Target a specific crate instead:

nix develop && \
just setup_test_envs && \
just initialize_dbs && \
just prepare_db && \
cargo test -p document_storage_service

---

Key Source Files and References

File	Purpose
docs/RUNNING_LOCALLY.md	Tool requirements and Nix shell instructions
CLAUDE.md	Exact just workflow and SQLx offline mode rules
CONTRIBUTING.md	Guidance for running cargo test -p <crate> on modified crates
Cargo.toml (workspace root)	Declares all member crates for just test
docker/docker-compose.yml	Service definitions for Postgres, Redis, LocalStack, OpenSearch, Kafka, FusionAuth
crates/*/README.md	Crate-specific test commands and target flags

---

Summary

To run tests in the macro repository successfully:

• Install Nix and Docker as the only required external tools
• Enter nix develop to load the complete development environment
• Start services with just run_local --no-doppler or individual docker compose commands
• Execute just setup_test_envs, just initialize_dbs, and just prepare_db before testing
• Run just test for the full suite or cargo test -p <crate> for targeted verification
• Keep SQLX_OFFLINE unset during test execution to maintain live database connectivity

---

Frequently Asked Questions

Do I need to install Rust directly to run tests in the macro repository?

No. The Nix development shell provides Cargo, the Rust toolchain, and all additional tools. Installing Rust separately is unnecessary and may cause version conflicts. Enter nix develop and all required binaries become available in your PATH.

Why do my tests fail with SQLx "no cached data" errors?

The SQLx query cache is out of sync with your database schema. Run just prepare_db to regenerate cached queries. If failures originate from test code specifically, use just prepare_db --tests to include test query validation in the cache refresh.

Can I run tests without starting all Docker services?

Yes. Most crate tests only require PostgreSQL. Start a minimal environment with docker compose -f docker/docker-compose.yml up -d postgres instead of the full stack. Reserve just run_local --no-doppler for end-to-end integration tests that exercise Redis, Kafka, OpenSearch, and other services.

What is the difference between just test and cargo test?

just test is a task runner shortcut that executes tests across the entire workspace. cargo test -p <crate> targets a specific package. Use just test for comprehensive validation and cargo test -p <crate> during iterative development on individual components.

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