fix: pass doctests, s/doctest/doctests/, run them in gha, s/asyncpg/psycopg/ in doctest, fix keycloak flakiness: wait for first user

.github/workflows/ci-community.yml

@@ -57,3 +57,5 @@ jobs:
         run: poetry install -E ${{ matrix.module }}
       - name: Run tests
         run: make modules/${{ matrix.module }}/tests
+      - name: Run doctests
+        run: make modules/${{ matrix.module }}/doctests

.github/workflows/ci-core.yml

@@ -28,3 +28,5 @@ jobs:
         run: poetry build && poetry run twine check dist/*.tar.gz
       - name: Run tests
         run: make core/tests
+      - name: Run doctests
+        run: make core/doctests

Makefile

@@ -11,7 +11,7 @@ UPLOAD = $(addsuffix /upload,${PACKAGES})
 # All */tests folders for each of the test suites.
 TESTS = $(addsuffix /tests,$(filter-out meta,${PACKAGES}))
 TESTS_DIND = $(addsuffix -dind,${TESTS})
-DOCTESTS = $(addsuffix /doctest,$(filter-out meta,${PACKAGES}))
+DOCTESTS = $(addsuffix /doctests,$(filter-out modules/README.md,${PACKAGES}))
 # All linting targets.
 LINT = $(addsuffix /lint,${PACKAGES})
 
@@ -56,10 +56,10 @@ ${TESTS_DIND} : %/tests-dind : image
 docs :
 	poetry run sphinx-build -nW . docs/_build
 
-doctest : ${DOCTESTS}
+doctests : ${DOCTESTS}
 	poetry run sphinx-build -b doctest . docs/_build
 
-${DOCTESTS} : %/doctest :
+${DOCTESTS} : %/doctests :
 	poetry run sphinx-build -b doctest -c doctests $* docs/_build
 
 # Remove any generated files.

conf.py

@@ -74,7 +74,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "meta/README.rst", ".venv"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv", ".git"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

index.rst

@@ -21,6 +21,7 @@ testcontainers-python facilitates the use of Docker containers for functional an
     modules/elasticsearch/README
     modules/google/README
     modules/influxdb/README
+    modules/k3s/README
     modules/kafka/README
     modules/keycloak/README
     modules/localstack/README
@@ -36,7 +37,6 @@ testcontainers-python facilitates the use of Docker containers for functional an
     modules/rabbitmq/README
     modules/redis/README
     modules/selenium/README
-    modules/k3s/README
 
 Getting Started
 ---------------
@@ -46,32 +46,32 @@ Getting Started
     >>> from testcontainers.postgres import PostgresContainer
     >>> import sqlalchemy
 
-    >>> with PostgresContainer("postgres:latest") as postgres:
+    >>> with PostgresContainer("postgres:16") as postgres:
     ...     psql_url = postgres.get_connection_url()
     ...     engine = sqlalchemy.create_engine(psql_url)
     ...     with engine.begin() as connection:
-    ...         result = connection.execute(sqlalchemy.text("select version()"))
-    ...         version, = result.fetchone()
+    ...         version, = connection.execute(sqlalchemy.text("SELECT version()")).fetchone()
     >>> version
-    'PostgreSQL ...'
+    'PostgreSQL 16...'
 
 The snippet above will spin up the current latest version of a postgres database in a container. The :code:`get_connection_url()` convenience method returns a :code:`sqlalchemy` compatible url (using the :code:`psycopg2` driver per default) to connect to the database and retrieve the database version.
 
 .. doctest::
 
-    >>> import asyncpg
     >>> from testcontainers.postgres import PostgresContainer
+    >>> import psycopg
 
     >>> with PostgresContainer("postgres:16", driver=None) as postgres:
-    ...     psql_url = container.get_connection_url()
-    ...     with asyncpg.create_pool(dsn=psql_url,server_settings={"jit": "off"}) as pool:
-    ...         conn = await pool.acquire()
-    ...         ret = await conn.fetchval("SELECT 1")
-    ...         assert ret == 1
+    ...     psql_url = postgres.get_connection_url()
+    ...     with psycopg.connect(psql_url) as connection:
+    ...         with connection.cursor() as cursor:
+    ...             version, = cursor.execute("SELECT version()").fetchone()
+    >>> version
+    'PostgreSQL 16...'
 
 This snippet does the same, however using a specific version and the driver is set to None, to influence the :code:`get_connection_url()` convenience method to not include a driver in the URL (e.g. for compatibility with :code:`psycopg` v3).
 
-Note, that the :code:`sqlalchemy` and :code:`psycopg2` packages are no longer a dependency of :code:`testcontainers[postgres]` and not needed to launch the Postgres container. Your project therefore needs to declare a dependency on the used driver and db access methods you use in your code.
+Note, that the :code:`sqlalchemy` and :code:`psycopg` packages are no longer a dependency of :code:`testcontainers[postgres]` and not needed to launch the Postgres container. Your project therefore needs to declare a dependency on the used driver and db access methods you use in your code.
 
 
 Installation

modules/keycloak/testcontainers/keycloak/__init__.py

@@ -17,7 +17,9 @@
 
 from keycloak import KeycloakAdmin
 from testcontainers.core.container import DockerContainer
-from testcontainers.core.waiting_utils import wait_container_is_ready
+from testcontainers.core.waiting_utils import wait_container_is_ready, wait_for_logs
+
+_DEFAULT_DEV_COMMAND = "start-dev"
 
 
 class KeycloakContainer(DockerContainer):
@@ -30,8 +32,9 @@ class KeycloakContainer(DockerContainer):
 
             >>> from testcontainers.keycloak import KeycloakContainer
 
-            >>> with KeycloakContainer() as kc:
-            ...    keycloak = kc.get_client()
+            >>> with KeycloakContainer(f"quay.io/keycloak/keycloak:24.0.1") as keycloak:
+            ...     keycloak.get_client().users_count()
+            1
     """
 
     def __init__(
@@ -55,7 +58,7 @@ def _configure(self) -> None:
         self.with_env("KC_HEALTH_ENABLED", "true")
         # Starting Keycloak in development mode
         # see: https://www.keycloak.org/server/configuration#_starting_keycloak_in_development_mode
-        self.with_command("start-dev")
+        self.with_command(_DEFAULT_DEV_COMMAND)
 
     def get_url(self) -> str:
         host = self.get_container_host_ip()
@@ -67,6 +70,8 @@ def _readiness_probe(self) -> None:
         # Keycloak provides an REST API endpoints for health checks: https://www.keycloak.org/server/health
         response = requests.get(f"{self.get_url()}/health/ready", timeout=1)
         response.raise_for_status()
+        if self._command == _DEFAULT_DEV_COMMAND:
+            wait_for_logs(self, "Added user .* to realm .*")
 
     def start(self) -> "KeycloakContainer":
         self._configure()

modules/keycloak/tests/test_keycloak.py

@@ -5,4 +5,4 @@
 @pytest.mark.parametrize("image_version", ["24.0.1", "18.0"])
 def test_docker_run_keycloak(image_version: str):
     with KeycloakContainer(f"quay.io/keycloak/keycloak:{image_version}") as keycloak_admin:
-        keycloak_admin.get_client().users_count()
+        assert keycloak_admin.get_client().users_count() == 1

modules/postgres/testcontainers/postgres/__init__.py

@@ -38,8 +38,7 @@ class PostgresContainer(DbContainer):
             >>> from testcontainers.postgres import PostgresContainer
             >>> import sqlalchemy
 
-            >>> postgres_container = PostgresContainer("postgres:16")
-            >>> with postgres_container as postgres:
+            >>> with PostgresContainer("postgres:16") as postgres:
             ...     engine = sqlalchemy.create_engine(postgres.get_connection_url())
             ...     with engine.begin() as connection:
             ...         result = connection.execute(sqlalchemy.text("select version()"))

modules/postgres/tests/test_postgres.py

@@ -1,5 +1,3 @@
-import sys
-
 import pytest
 
 from testcontainers.postgres import PostgresContainer

pyproject.toml

@@ -5,7 +5,8 @@ description = "Python library for throwaway instances of anything that can run i
 authors = ["Sergey Pirogov <automationremarks@gmail.com>"]
 maintainers = [
     "Balint Bartha <totallyzen@users.noreply.github.com>",
-    "David Ankin <daveankin@gmail.com>"
+    "David Ankin <daveankin@gmail.com>",
+    "Vemund Santi <vemund@santi.no>"
 ]
 readme = "README.md"
 keywords = ["testing", "logging", "docker", "test automation"]
@@ -120,6 +121,7 @@ anyio = "^4.3.0"
 psycopg2-binary = "*"
 pg8000 = "*"
 sqlalchemy = "*"
+psycopg = "*"
 kafka-python = "^2.0.2"
 
 [[tool.poetry.source]]