docs/testing.md

# Testing the Gerrit MCP Server

This project includes a comprehensive test suite to ensure the server functions correctly and remains stable. We use **pytest** as our testing framework.

## Quick Start

The easiest way to run the tests is to use `pytest` from the root of the project.

1.  **Build the Environment**:
    Run the build script to set up the virtual environment and install dependencies:
    ```bash
    ./build-gerrit.sh
    ```

2.  **Activate Virtual Environment**:
    ```bash
    source .venv/bin/activate
    ```

3.  **Run Tests**:
    ```bash
    pytest
    ```

## Test Structure

The tests are organized as follows:

*   `tests/unit/`: **Fast, isolated tests.** These tests verify individual functions and classes in isolation. External dependencies like `curl` and file system operations are mocked to ensure speed and determinism. They are the first line of defense.
*   `tests/integration/`: **Component interaction tests.** These tests verify that different parts of the application work together correctly. While they still mock external network calls (to avoid flakiness), they test the flow of data through the system, including configuration loading and command execution logic.
*   `tests/e2e/`: **End-to-End tests.** These tests run against a live Gerrit instance. They are optional and require specific configuration. They verify that the server can actually communicate with a real Gerrit server and perform actions like querying changes and posting comments.

## Writing Tests

Tests should be simple, readable, and follow the "Arrange, Act, Assert" pattern. We use `pytest` fixtures for setup and dependency injection.

### Example: Unit Test
```python
import pytest
from unittest.mock import patch
from gerrit_mcp_server import main

@pytest.mark.asyncio
async def test_get_bugs_from_cl():
    """The hero finds the bugs hidden in the message."""
    with patch("gerrit_mcp_server.main.run_curl") as mock_run_curl:
        mock_run_curl.return_value = '{"message": "Fixes: b/12345"}'
        result = await main.get_bugs_from_cl("123")
        assert "Found bug(s): 12345" in result[0]["text"]
```

## End-to-End (E2E) Tests

To run E2E tests, you need a `tests/e2e/e2e_config.json` file (see `tests/e2e/e2e_config.sample.json`).

**Note:** This configuration file is **required** for E2E tests to know which Gerrit instance to target and what credentials to use.

Run them with:
```bash
pytest tests/e2e
```