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

Run tests from the project root (no venv activation needed):

```bash
uv run pytest
```

If you haven't run `./build-gerrit.sh` yet, `uv run` will set up the virtual
environment automatically on first use.

## 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
```