test(d1): tests/integration/ + Testcontainers MySQL harness

延续 v0.2.2 末尾"凭据清理"的方向 - 让集成测试可以在零外部依赖
(Docker 拉 MySQL 8.0 容器) 下跑完。

新增:
- tests/integration/conftest.py: 提供 mysql_container session fixture
  * 优先用 DBJAVAGENIX_TEST_DB_HOST (env-var 路径,生产 DB)
  * 否则用 testcontainers 起 MySQL 8.0 容器
  * --no-docker flag 跳过所有依赖 Docker 的测试
  * testcontainers / Docker 任一缺失 → pytest.skip() 而不是 fail
- tests/integration/test_harness_smoke.py: 2 个 meta-test 验证 fixture 本身

pyproject.toml: 新增 optional-deps `integration` = testcontainers[mysql,postgres]

Why: 凭据清理后必须给"如何在 CI 跑集成测试"一个标准答案。Testcontainers
是社区共识 (Java Spring Boot 测试也基本都走它),Python 版 API 成熟。

D1 是 v0.3 多 dialect 工作 (D2-D3 PostgreSQL) 的地基。

Author: ZhaoXingPeng

pyproject.toml

@@ -51,6 +51,10 @@ dev = [
     "pre-commit>=4.0.0",
 ]
 
+integration = [
+    "testcontainers[mysql,postgres]>=4.8.0",
+]
+
 docs = [
     "mkdocs>=1.5.0",
     "mkdocs-material>=9.0.0",

tests/integration/__init__.py

@@ -0,0 +1,127 @@
+"""Pytest harness for integration tests against ephemeral DB containers.
+
+Uses `testcontainers` (https://testcontainers-python.readthedocs.io/) to spin
+up real MySQL / PostgreSQL via Docker for each test session. This replaces
+the previous workflow of pointing at a fixed shared dev DB (which leaked
+credentials and required network access from CI).
+
+If `testcontainers` is not installed, or Docker is not available, the
+fixtures `skip()` instead of erroring so unit tests can still run.
+
+Usage:
+
+    pytest tests/integration/                # auto-spins MySQL container
+    pytest tests/integration/ --no-docker    # skips all integration tests
+
+The legacy env-var path (DBJAVAGENIX_TEST_DB_HOST) is still respected via
+`existing_db_config` for runs against a real shared DB.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+from typing import Optional
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# CLI flag: --no-docker disables container-based fixtures entirely
+# ---------------------------------------------------------------------------
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--no-docker",
+        action="store_true",
+        default=False,
+        help="Skip integration tests that need Docker / testcontainers.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _docker_available() -> bool:
+    """Best-effort check: probe `docker` socket / pipe without subprocess."""
+    if os.name == "nt":
+        # Windows: Docker Desktop pipe at \\.\pipe\docker_engine — hard to probe
+        # without ctypes. Defer to import-time error from testcontainers.
+        return True
+    return os.path.exists("/var/run/docker.sock")
+
+
+def _testcontainers_available() -> bool:
+    try:
+        import testcontainers  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def _port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    """Quick TCP probe — used to verify container is ready."""
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def existing_db_config() -> Optional[dict]:
+    """If user exported DBJAVAGENIX_TEST_DB_HOST, use that instead of a container."""
+    from tests._db_config import get_test_db_config
+    return get_test_db_config()
+
+
+@pytest.fixture(scope="session")
+def mysql_container(request, existing_db_config):
+    """Yields a dict { host, port, user, password, database, database_type }.
+
+    Resolution order:
+      1. If --no-docker flag set: skip
+      2. If existing_db_config exists (env vars): use it
+      3. If testcontainers + docker available: spin up MySQL container
+      4. Otherwise: skip with reason
+    """
+    if request.config.getoption("--no-docker"):
+        pytest.skip("--no-docker passed")
+
+    if existing_db_config and existing_db_config["database_type"] == "mysql":
+        # Trust env-var DB. Verify reachable before yielding.
+        if not _port_open(existing_db_config["host"], existing_db_config["port"]):
+            pytest.skip(
+                f"DBJAVAGENIX_TEST_DB_HOST={existing_db_config['host']}:"
+                f"{existing_db_config['port']} not reachable"
+            )
+        yield existing_db_config
+        return
+
+    if not _testcontainers_available():
+        pytest.skip(
+            "testcontainers not installed (pip install dbjavagenix[integration])"
+        )
+    if not _docker_available():
+        pytest.skip("Docker not available")
+
+    from testcontainers.mysql import MySqlContainer  # type: ignore
+
+    with MySqlContainer("mysql:8.0") as container:
+        config = {
+            "host": container.get_container_host_ip(),
+            "port": int(container.get_exposed_port(3306)),
+            "username": container.username,
+            "password": container.password,
+            "database": container.dbname,
+            "database_type": "mysql",
+        }
+        yield config

tests/integration/conftest.py

@@ -0,0 +1,25 @@
+"""Smoke test: container fixture yields a usable DB config.
+
+This is a meta-test of the harness itself — it doesn't depend on
+DBJavaGenix application code. If this passes, downstream integration tests
+for discovery / codegen can build on the same fixture.
+"""
+
+from __future__ import annotations
+
+
+def test_mysql_container_yields_config(mysql_container):
+    """The fixture returns a dict with all expected keys."""
+    assert isinstance(mysql_container, dict)
+    for key in ("host", "port", "username", "password", "database", "database_type"):
+        assert key in mysql_container, f"missing key {key}"
+    assert mysql_container["database_type"] == "mysql"
+    assert isinstance(mysql_container["port"], int)
+    assert mysql_container["port"] > 0
+
+
+def test_mysql_container_reachable(mysql_container):
+    """We can actually open a TCP connection to the yielded host:port."""
+    from tests.integration.conftest import _port_open
+
+    assert _port_open(mysql_container["host"], mysql_container["port"], timeout=5.0)