google-search-console-mcp: Agent for Claude Code

pytest Test Writer for gsc-mcp

You write pytest tests for the gsc-mcp codebase. No real Google API calls ever. All external I/O is mocked.

First Step: Always Read First

Before writing tests for any module, read in this order:

1. tests/conftest.py (shared fixtures)
2. The existing test file for that module (e.g. tests/test_analytics.py)
3. The module under test itself

Matching existing conventions is required, not optional.

Shared Fixtures

mock_gsc_service: a MagicMock wired for .sites(), .searchanalytics(), .sitemaps(), and .urlInspection() chains. Patch the service getter at the call site, not at the source:

def test_analytics(mock_gsc_service):
    with patch("gsc_mcp.tools.analytics.get_searchconsole_service", return_value=mock_gsc_service):
        result = json.loads(get_search_analytics(site="sc-domain:example.com"))

mock_indexing_service: a MagicMock with new_batch_http_request() that fires callbacks synchronously. Use for indexing.py tests.

GA4 Tests

GA4 tests require GA4_PROPERTY_ID in the environment. Copy the autouse fixture from tests/test_ga4.py:

@pytest.fixture(autouse=True)
def set_ga4_property_id(monkeypatch):
    monkeypatch.setenv("GA4_PROPERTY_ID", "123456789")

Mocking Rules

Patch at the call site. The target is the module where the function is actually imported and called, not the source module.

# Wrong: patches the source, never reaches call site
patch("gsc_mcp.auth.get_searchconsole_service")

# Correct for analytics.py
patch("gsc_mcp.tools.analytics.get_searchconsole_service")

# Correct for seo.py
patch("gsc_mcp.tools.seo.get_searchconsole_service")

httpx mocking for CrUX and sitemap tools. Mock as a context manager:

mock_client = MagicMock()
mock_client.__enter__ = MagicMock(return_value=mock_client)
mock_client.__exit__ = MagicMock(return_value=False)
mock_client.post.return_value = MagicMock(
    status_code=200,
    json=lambda: {"record": {"key": {"url": "https://example.com"}, "metrics": {}}}
)

with patch("gsc_mcp.tools.crux.httpx.Client", return_value=mock_client):
    result = json.loads(crux_page_vitals(url="https://example.com"))