How to Run Tests for the Goose Project: A Complete Cargo Guide

Activate the Hermit environment and execute cargo test to run the full Rust test suite across the aaif-goose/goose workspace, or target specific crates with cargo test -p goose.

The aaif-goose/goose repository is a Rust-based agent framework organized as a Cargo workspace. Understanding how to run tests for the Goose project ensures you can validate changes to the core agent logic or MCP extensions before submitting contributions.

Environment Setup

Before executing any test commands, you must activate the project's Hermit environment. This step is documented in both AGENTS.md and CONTRIBUTING.md at the repository root.

source bin/activate-hermit

Once activated, the cargo toolchain becomes available and you can proceed with the testing workflow.

Test Commands and Scopes

The Goose test suite supports execution at multiple granularity levels. Choose the appropriate command based on whether you need full coverage or targeted validation.

Run the Complete Test Suite

To execute every unit test and integration test across all workspace crates, use the standard Cargo command:

cargo test

This builds each crate defined in the root Cargo.toml, runs #[cfg(test)] modules co-located with source files, and executes integration tests from the crates/*/tests/ directories. Cargo automatically parallelizes execution across CPU cores.

Target the Core Goose Crate

When iterating on the primary agent logic located in crates/goose/, limit the scope to avoid building unrelated extensions:

cargo test -p goose

The -p (or --package) flag restricts testing to the specified crate, significantly reducing compile times during development.

Execute MCP Integration Tests

Changes to Model Context Protocol extensions in crates/goose-mcp/ require validation through the dedicated integration test harness. Run the specific test file crates/goose/tests/mcp_integration_test.rs with:

cargo test --package goose --test mcp_integration_test

This command builds and executes only the MCP integration test, verifying that protocol extensions interact correctly with the core agent.

Record MCP Test Fixtures

When MCP test expectations change, regenerate the underlying fixtures using the Just command defined in the project justfile:

just record-mcp-tests

This updates the captured data used by the MCP test harness, ensuring subsequent test runs compare against current behavior.

Test Architecture Overview

Understanding the workspace structure helps you locate relevant tests efficiently. The repository organizes code into multiple crates under crates/, with unit tests embedded alongside source code using #[cfg(test)] modules, and integration tests residing in dedicated tests/ subdirectories within each crate folder.

The MCP integration framework specifically lives at crates/goose/tests/mcp_integration_test.rs and depends on serialized fixtures that you can refresh via the just record-mcp-tests recipe. This architecture separates core agent logic from extension protocols while maintaining comprehensive coverage.

Summary

• Activate Hermit first: Run source bin/activate-hermit to access the development toolchain.
• Full suite: Use cargo test to validate the entire workspace.
• Crate-specific: Use cargo test -p goose to focus on the core agent.
• MCP validation: Use cargo test --package goose --test mcp_integration_test for extension testing.
• Fixture updates: Use just record-mcp-tests when MCP test data requires regeneration.

Frequently Asked Questions

Do I need to install Rust manually to run Goose tests?

No. The aaif-goose/goose repository uses Hermit to manage the Rust toolchain. Once you run source bin/activate-hermit, the correct Cargo and compiler versions become available automatically without system-wide installation.

Where are the integration tests located in the Goose repository?

Integration tests reside in crates/<crate-name>/tests/ directories. For example, the MCP integration test is located at crates/goose/tests/mcp_integration_test.rs. Unit tests are co-located with source files using #[cfg(test)] modules.

How do I run only the tests for MCP extensions?

Execute cargo test --package goose --test mcp_integration_test to run only the MCP integration test harness. If you have modified the extensions themselves in crates/goose-mcp/, you may also need to run just record-mcp-tests to update the test fixtures before testing.

What should I do if the MCP integration test fails after modifying extensions?

Run just record-mcp-tests to regenerate the test fixtures that the MCP integration test compares against. This command, defined in the repository justfile, captures current MCP behavior so the test suite validates against updated expectations.

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