# How to Run Tests in the Macro Repository: A Complete Guide > Learn how to run tests in the macro repository. Follow our guide to prepare your database environment and execute tests efficiently using Nix and Docker. - Repository: [Macro/macro](https://github.com/macro-inc/macro) - Tags: how-to-guide - Published: 2026-08-20 --- **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 ` 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](https://nix.dev/install-nix) and Docker from [docs.docker.com/get-docker](https://docs.docker.com/get-docker/). These are the only required tools according to [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/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: ```bash 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: ```bash nix develop --extra-experimental-features nix-command \ --extra-experimental-features flakes ``` This workflow is documented in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/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: ```bash 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: ```bash 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`](https://github.com/macro-inc/macro/blob/main/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: ```bash 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`](https://github.com/macro-inc/macro/blob/main/CLAUDE.md)【/cache/repos/github.com/macro-inc/macro/main/CLAUDE.md#L81-L86】 and [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/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 ```bash just test ``` This command walks the workspace [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) and executes tests for all 80+ member crates. ### Target a Specific Crate ```bash cargo test -p document_storage_service ``` Replace `document_storage_service` with any crate name from the workspace. This approach is recommended in [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/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`: ```bash 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`](https://github.com/macro-inc/macro/blob/main/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: ```bash just prepare_db --tests # Include --tests flag for test-code cache issues cargo test -p ``` 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: ```bash nix develop && \ just setup_test_envs && \ just initialize_dbs && \ just prepare_db && \ just test ``` Target a specific crate instead: ```bash 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`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | Tool requirements and Nix shell instructions | | [`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/CLAUDE.md) | Exact `just` workflow and SQLx offline mode rules | | [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) | Guidance for running `cargo test -p ` on modified crates | | [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) (workspace root) | Declares all member crates for `just test` | | [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/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 ` 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 ` targets a specific package. Use `just test` for comprehensive validation and `cargo test -p ` during iterative development on individual components.