feat(tests): add local integration test suite for proxy and plugins

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nik-localstack

Makefile

@@ -1,17 +1,65 @@
 VENV_DIR ?= .venv
 VENV_RUN = . $(VENV_DIR)/bin/activate
 PIP_CMD ?= pip
+PYTHON_CMD ?= python
+TEST_DEPS ?= pytest pytest-timeout
+LINT_DEPS ?= ruff
+
+PG_TEST_CONTAINER ?= pg-proxy-local-tests
+PG_TEST_IMAGE ?= postgres:16
+PG_TEST_PORT ?= 55432
+PG_TEST_USER ?= postgres
+PG_TEST_PASSWORD ?= postgres
+PG_TEST_DB ?= postgres
 
 usage:             ## Show this help
 	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
 
 install:           ## Install dependencies in local virtualenv folder
-	(test `which virtualenv` || $(PIP_CMD) install --user virtualenv) && \
+	(test `which virtualenv` || $(PIP_CMD) install virtualenv) && \
 		(test -e $(VENV_DIR) || virtualenv $(VENV_OPTS) $(VENV_DIR)) && \
 		($(VENV_RUN) && $(PIP_CMD) install --upgrade pip) && \
 		(test ! -e requirements.txt || ($(VENV_RUN); $(PIP_CMD) install -r requirements.txt))
 
 publish:           ## Publish the library to the central PyPi repository
 	($(VENV_RUN); pip install twine; python ./setup.py sdist && twine upload dist/*)
 
-.PHONY: usage install clean publish test lint
+install-test: install ## Install test dependencies in local virtualenv
+	($(VENV_RUN); $(PIP_CMD) install $(TEST_DEPS))
+
+install-lint: install ## Install lint dependencies in local virtualenv
+	($(VENV_RUN); $(PIP_CMD) install $(LINT_DEPS))
+
+lint: install-lint ## Format code with ruff
+	$(VENV_DIR)/bin/ruff format postgresql_proxy tests plugins
+
+test: ## Start local PostgreSQL container and run all tests
+	@set -euo pipefail; \
+	cleanup() { docker rm -f $(PG_TEST_CONTAINER) >/dev/null 2>&1 || true; }; \
+	trap cleanup EXIT INT TERM; \
+	docker rm -f $(PG_TEST_CONTAINER) >/dev/null 2>&1 || true; \
+	docker run --name $(PG_TEST_CONTAINER) \
+		-e POSTGRES_USER=$(PG_TEST_USER) \
+		-e POSTGRES_PASSWORD=$(PG_TEST_PASSWORD) \
+		-e POSTGRES_DB=$(PG_TEST_DB) \
+		-p $(PG_TEST_PORT):5432 \
+		-d $(PG_TEST_IMAGE) >/dev/null; \
+	for i in $$(seq 1 45); do \
+		if docker exec $(PG_TEST_CONTAINER) pg_isready -U $(PG_TEST_USER) >/dev/null 2>&1; then \
+			echo "PostgreSQL ready on 127.0.0.1:$(PG_TEST_PORT)"; \
+			break; \
+		fi; \
+		sleep 1; \
+	done; \
+	if ! docker exec $(PG_TEST_CONTAINER) pg_isready -U $(PG_TEST_USER) >/dev/null 2>&1; then \
+		echo "PostgreSQL did not become ready in time"; \
+		exit 1; \
+	fi; \
+	E2E_PG_HOST=127.0.0.1 \
+	E2E_PG_PORT=$(PG_TEST_PORT) \
+	E2E_PG_USER=$(PG_TEST_USER) \
+	E2E_PG_PASSWORD=$(PG_TEST_PASSWORD) \
+	E2E_PG_DB=$(PG_TEST_DB) \
+	$(VENV_DIR)/bin/$(PYTHON_CMD) -m pytest -vv
+
+.PHONY: usage install install-test install-lint clean publish test lint

README.md

@@ -81,3 +81,11 @@ If you want to test it, do this. Otherwise scroll down for instructions on how t
   - add stop() method to proxy; refactor logging
 - v0.0.2
   - fix socket file descriptors under Linux
+
+## Testing
+
+Run the full local test suite (starts a disposable PostgreSQL container automatically):
+
+```bash
+make test
+```

tests/README.md

@@ -0,0 +1,62 @@
+# Testing Guide
+
+All tests in this repo require a real PostgreSQL server and are organized at the top level:
+
+- `test_proxy.py`: proxy behavior tests (connection, SSL, hang regressions)
+- `test_plugins.py`: plugin integration tests (HLL rewrite behavior)
+
+## Prerequisites
+
+- Python `3.13` (same version as CI)
+- Docker (for local disposable PostgreSQL)
+- `psql` (`postgresql-client`)
+- `openssl` (SSL tests generate a temporary self-signed cert/key at runtime)
+
+Install Python deps in the project virtualenv:
+
+```bash
+make install-test
+```
+
+## Which command should I use?
+
+- Fastest full local run with disposable Postgres: `make test`
+- Run only proxy tests (using your own Postgres): `python -m pytest tests/test_proxy.py -vv`
+- Run only plugin tests: `python -m pytest tests/test_plugins.py -vv`
+
+## 1) Full local suite (recommended)
+
+`make test` starts a temporary PostgreSQL container, waits for readiness, sets DB env vars, then runs:
+
+```bash
+python -m pytest -vv
+```
+
+Use it when you want one command that matches normal contributor workflow.
+
+```bash
+make test
+```
+
+## 2) DB-backed proxy tests against an existing PostgreSQL
+
+If you already have PostgreSQL running, set connection env vars and run only proxy tests:
+
+```bash
+export E2E_PG_HOST=127.0.0.1
+export E2E_PG_PORT=5432
+export E2E_PG_USER=postgres
+export E2E_PG_PASSWORD=postgres
+export E2E_PG_DB=postgres
+python -m pytest tests/test_proxy.py -vv
+```
+
+If PostgreSQL is not reachable, tests fail fast at startup.
+
+## 3) Plugin integration tests
+
+```bash
+python -m pytest tests/test_plugins.py -vv
+```
+
+Requires PostgreSQL to be running with the `E2E_PG_*` env vars set (see section 2).

tests/conftest.py

@@ -0,0 +1,33 @@
+import os
+
+import psycopg2
+import pytest
+
+
+@pytest.fixture(scope="session")
+def postgres_settings():
+    """PostgreSQL connection settings from environment or defaults."""
+    return {
+        "host": os.environ.get("E2E_PG_HOST", "127.0.0.1"),
+        "port": int(os.environ.get("E2E_PG_PORT", "5432")),
+        "user": os.environ.get("E2E_PG_USER", "postgres"),
+        "password": os.environ.get("E2E_PG_PASSWORD", "postgres"),
+        "dbname": os.environ.get("E2E_PG_DB", "postgres"),
+    }
+
+
+@pytest.fixture(scope="session", autouse=True)
+def ensure_postgres_available(postgres_settings):
+    """Ensure PostgreSQL backend is available before running any tests."""
+    try:
+        with psycopg2.connect(
+            connect_timeout=3, sslmode="disable", **postgres_settings
+        ) as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT 1")
+                assert cur.fetchone() == (1,)
+    except Exception as err:  # pragma: no cover - environment dependent
+        pytest.fail(
+            f"PostgreSQL backend is required for tests but is not reachable: {err}"
+        )
+

tests/test_plugins.py

@@ -0,0 +1,86 @@
+"""Plugin integration tests.
+
+These tests verify we can load plugins and that plugin behavior works against a real Postgres backend.
+"""
+
+import collections
+import importlib
+
+import psycopg2
+import pytest
+
+import plugins.tableau_hll as hll
+
+
+@pytest.fixture()
+def plugin_context(postgres_settings, monkeypatch):
+    # plugin's internal psycopg2 connection does not pass password, so provide it via libpq env var
+    monkeypatch.setenv("PGPASSWORD", postgres_settings["password"])
+
+    with psycopg2.connect(sslmode="disable", **postgres_settings) as conn:
+        conn.autocommit = True
+        with conn.cursor() as cur:
+            cur.execute('CREATE SCHEMA IF NOT EXISTS "crm_dim";')
+            cur.execute('DROP TABLE IF EXISTS "crm_dim"."crm_data_source";')
+            cur.execute(
+                """
+                DO $$
+                BEGIN
+                    IF EXISTS (SELECT 1 FROM pg_type WHERE typname = 'hll' AND typtype = 'd') THEN
+                        DROP DOMAIN hll;
+                    END IF;
+                    IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'hll') THEN
+                        CREATE TYPE hll AS (v text);
+                    END IF;
+                END $$;
+                """
+            )
+            cur.execute(
+                'CREATE TABLE "crm_dim"."crm_data_source" ('
+                '"Set of Customers" hll, '
+                '"Campaign Name" text);'
+            )
+
+    InstanceConfig = collections.namedtuple("InstanceConfig", "redirect")
+    Redirect = collections.namedtuple("Redirect", "name host port")
+    return {
+        "instance_config": InstanceConfig(
+            redirect=Redirect(
+                name="postgres",
+                host=postgres_settings["host"],
+                port=postgres_settings["port"],
+            )
+        ),
+        "connect_params": {
+            "user": postgres_settings["user"],
+            "database": postgres_settings["dbname"],
+        },
+    }
+
+
+def test_rewrite_query_for_hll_column(plugin_context):
+    src = (
+        'SELECT COUNT(DISTINCT "crm_data_source"."Set of Customers") AS "ctd:Set of Customers:ok"\n'
+        'FROM "crm_dim"."crm_data_source" "crm_data_source"\n'
+        "HAVING (COUNT(1) > 0);"
+    )
+
+    res = hll.rewrite_query(src, plugin_context)
+    assert "hll_cardinality(hll_union_agg" in res
+
+
+def test_plugin_module_loads_and_exposes_rewriter():
+    module = importlib.import_module("plugins.tableau_hll")
+    assert hasattr(module, "rewrite_query")
+    assert callable(module.rewrite_query)
+
+
+def test_does_not_rewrite_non_hll_column(plugin_context):
+    src = (
+        'SELECT COUNT(DISTINCT "crm_data_source"."Campaign Name") AS "ctd:Campaign Name:ok"\n'
+        'FROM "crm_dim"."crm_data_source" "crm_data_source"\n'
+        "HAVING (COUNT(1) > 0);"
+    )
+
+    res = hll.rewrite_query(src, plugin_context)
+    assert "hll_cardinality(hll_union_agg" not in res