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

> Easily run tests for the Goose project with Cargo. Learn how to execute the full Rust test suite or target specific crates for efficient testing in the aaif-goose/goose repository.

- Repository: [goose/goose](https://github.com/aaif-goose/goose)
- Tags: testing-guide
- Published: 2026-04-07

---

**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`](https://github.com/aaif-goose/goose/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/aaif-goose/goose/blob/main/CONTRIBUTING.md) at the repository root.

```bash
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:

```bash
cargo test

```

This builds each crate defined in the root [`Cargo.toml`](https://github.com/aaif-goose/goose/blob/main/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:

```bash
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`](https://github.com/aaif-goose/goose/blob/main/crates/goose/tests/mcp_integration_test.rs) with:

```bash
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`:

```bash
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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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.