Merge branch 'checkup-reports-tests' into 'main'

Add Postgres reporter generator and integration tests

See merge request postgres-ai/postgres_ai!77

Author: Sarumyan

.gitignore

@@ -28,6 +28,14 @@ pids
 *.seed
 *.pid.lock
 
+# Python artifacts
+__pycache__/
+*.py[cod]
+
+# Python virtual environments
+.venv/
+venv/
+
 # Node artifacts
 node_modules/
 cli/node_modules/

.gitlab-ci.yml

@@ -1,6 +1,25 @@
 stages:
   - test
 
+reporter:tests:
+  stage: test
+  image: python:3.11-bullseye
+  variables:
+    GIT_STRATEGY: fetch
+    PIP_DISABLE_PIP_VERSION_CHECK: "1"
+    PIP_NO_CACHE_DIR: "1"
+  before_script:
+    - python --version
+    - pip install --upgrade pip
+    - apt-get update
+    - apt-get install -y --no-install-recommends postgresql postgresql-client && rm -rf /var/lib/apt/lists/*
+    - pip install -r reporter/requirements-dev.txt
+  script:
+    - chown -R postgres:postgres "$CI_PROJECT_DIR"
+    - su - postgres -c "cd \"$CI_PROJECT_DIR\" && python -m pytest --run-integration tests/reporter"
+  rules:
+    - if: '$CI_COMMIT_BRANCH'
+
 cli:smoke:test:
   stage: test
   image: alpine:3.20

README.md

@@ -248,6 +248,54 @@ Get your access token at [PostgresAI](https://postgres.ai) for automated report
 - Query plan analysis and automated recommendations
 - Enhanced AI integration capabilities
 
+## 🧪 Testing
+
+Python-based report generation lives under `reporter/` and now ships with a pytest suite.
+
+### Installation
+
+Install dev dependencies (includes `pytest`, `pytest-postgresql`, `psycopg`, etc.):
+```bash
+python3 -m pip install -r reporter/requirements-dev.txt
+```
+
+### Running Tests
+
+#### Unit Tests Only (Fast, No External Services Required)
+
+Run only unit tests with mocked Prometheus interactions:
+```bash
+pytest tests/reporter
+```
+
+This automatically skips integration tests. Or run specific test files:
+```bash
+pytest tests/reporter/test_generators_unit.py -v
+pytest tests/reporter/test_formatters.py -v
+```
+
+#### All Tests: Unit + Integration (Requires PostgreSQL)
+
+Run the complete test suite (both unit and integration tests):
+```bash
+pytest tests/reporter --run-integration
+```
+
+Integration tests create a temporary PostgreSQL instance automatically and require PostgreSQL binaries (`initdb`, `postgres`) on your PATH. No manual database setup or environment variables are required - the tests create and destroy their own temporary PostgreSQL instances.
+
+**Summary:**
+- `pytest tests/reporter` → **Unit tests only** (integration tests skipped)
+- `pytest tests/reporter --run-integration` → **Both unit and integration tests**
+
+### Test Coverage
+
+Generate coverage report:
+```bash
+pytest tests/reporter -m unit --cov=reporter --cov-report=html
+```
+
+View the coverage report by opening `htmlcov/index.html` in your browser.
+
 ## 🤝 Contributing
 
 We welcome contributions from Postgres experts! Please check our [GitLab repository](https://gitlab.com/postgres-ai/postgres_ai) for:

pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+addopts = -ra --import-mode=importlib
+pythonpath = .
+testpaths = tests
+markers =
+    unit: Marks fast unit tests that mock external services.
+    integration: Marks tests that talk to real services like PostgreSQL.
+    requires_postgres: Alias for tests needing a live Postgres instance.

reporter/__init__.py

@@ -0,0 +1 @@
+"""Reporter package exposing report generation utilities."""

reporter/requirements-dev.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+pytest==9.0.1
+pytest-postgresql==7.0.2
+coverage==7.6.10
+pytest-cov==6.0.0

reporter/requirements.txt

@@ -1,2 +1,2 @@
-requests>=2.31.0
-psycopg2-binary>=2.9.9 
+requests==2.32.5
+psycopg2-binary==2.9.11 

tests/__init__.py

@@ -0,0 +1,58 @@
+from typing import Callable
+
+import pytest
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Add a flag for enabling integration tests that require services."""
+    parser.addoption(
+        "--run-integration",
+        action="store_true",
+        default=False,
+        help="Run tests marked as integration/requires_postgres.",
+    )
+
+
+def pytest_collection_modifyitems(config: pytest.Config, items: list[pytest.Item]) -> None:
+    """Skip integration tests unless --run-integration is given."""
+    if config.getoption("--run-integration"):
+        return
+
+    skip_marker = pytest.mark.skip(reason="integration tests require --run-integration")
+    for item in items:
+        if "integration" in item.keywords or "requires_postgres" in item.keywords:
+            item.add_marker(skip_marker)
+
+
+@pytest.fixture(name="prom_result")
+def fixture_prom_result() -> Callable[[list[dict] | None, str], dict]:
+    """Build a Prometheus-like payload for the happy-path tests."""
+
+    def _builder(rows: list[dict] | None = None, status: str = "success") -> dict:
+        return {
+            "status": status,
+            "data": {
+                "result": rows or [],
+            },
+        }
+
+    return _builder
+
+
+@pytest.fixture(name="series_sample")
+def fixture_series_sample() -> Callable[[str, dict | None, list[tuple[float | int, float | int | str]] | None], dict]:
+    """Create metric entries (metric metadata + values array) for query_range tests."""
+
+    def _builder(
+        metric_name: str,
+        labels: dict | None = None,
+        values: list[tuple[float | int, float | int | str]] | None = None,
+    ) -> dict:
+        labels = labels or {}
+        values = values or []
+        return {
+            "metric": {"__name__": metric_name, **labels},
+            "values": [[ts, str(val)] for ts, val in values],
+        }
+
+    return _builder