Support for local SMS server for lab testing (#10)

* feat: twilio endpoints

* feat: dockerfile for twilio shim

* feat: support for automatic twilio shim

* build: support for building twilio-shim

* feat: addn suport to sms tools and testing

* fix: double api key print + cleanup labs on target run

* ci: fix source wording

Author: syntaxsdev

Makefile

@@ -20,10 +20,20 @@ patch_templates:
 	rm -rf $$VENV
 
 tests:
-	uv run pytest -rs -m e2e
+	@set -e; \
+	uv run pytest -rs -v -s -m e2e || exit 0; \
+	$(MAKE) clean-tests
+
 
 clean-tests:
-	@source .venv/bin/activate && \
+	@. .venv/bin/activate && \
 	appwrite-lab stop test-lab
 
-.PHONY: patch_templates tests clean-tests build_appwrite_cli build_appwrite_playwright
+build_twilio_shim:
+	cd twilio-shim && docker buildx build  -t docker.io/syntaxsdev/twilio-shim:latest -f Dockerfile . --load
+
+push_twilio_shim:
+	cd twilio-shim && docker buildx build  -t docker.io/syntaxsdev/twilio-shim:latest -f Dockerfile . --load --push
+
+
+.PHONY: patch_templates tests clean-tests build_appwrite_cli build_appwrite_playwright build_twilio_shim push_twilio_shim

appwrite_lab/_orchestrator.py

@@ -132,10 +132,11 @@ def get_running_pods_by_project(self, name: str):
         }
         return pods
 
-    def _deploy_service(
+    def _deploy_compose_service(
         self,
         project: str,
-        template_path: Path,
+        template_paths: list[Path] | Path,
+        env_file: Path | None = None,
         env_vars: dict[str, str] = {},
         extra_args: list[str] = [],
     ):
@@ -144,22 +145,29 @@ def _deploy_service(
 
         Args:
             project: The name of the project to deploy the service to.
-            template_path: The path to the template to use for the service.
+            template_paths: The path to the template to use for the service.
             env_vars: The environment variables to set.
+            env_file: The path to the environment file to use for the service.
             extra_args: Extra arguments to pass to the compose command.
         """
-        new_env = {**os.environ, **env_vars}
+        if isinstance(template_paths, Path):
+            template_paths = [template_paths]
+
+        file_overlays = []
+        for path in template_paths:
+            file_overlays.extend(["-f", str(path)])
+
         cmd = [
             *self.compose,
-            "-f",
-            template_path,
+            *file_overlays,
+            *(["--env-file", str(env_file)] if env_file else []),
             "-p",
             project,
             *extra_args,
             "up",
             "-d",
         ]
-        return self._run_cmd_safely(cmd, envs=new_env)
+        return self._run_cmd_safely(cmd, envs=env_vars)
 
     def deploy_appwrite_lab(
         self,
@@ -188,24 +196,38 @@ def deploy_appwrite_lab(
                 error=True, message=f"Lab '{name}' already deployed.", data=None
             )
         converted_version = version.replace(".", "_")
+
+        # Gather paths
         template_path = (
             Path(__file__).parent
             / "templates"
             / f"docker_compose_{converted_version}.yml"
         )
+
+        twilio_shim_path = (
+            Path(__file__).parent
+            / "templates"
+            / "extras"
+            / "twilio-shim"
+            / "docker_compose.yml"
+        )
+
+        env_file = Path(__file__).parent / "templates" / "environment" / "dotenv"
         if not template_path.exists():
             return Response(
                 error=True, message=f"Template {version} not found.", data=None
             )
 
-        # Override default env vars
+        # Override default env vars for port
         env_vars = get_env_vars(self.default_env_vars)
         if port != 80:
             env_vars["_APP_PORT"] = str(port)
 
         # What actually deploys the initial appwrite service
-        cmd_res = self._deploy_service(
-            project=name, template_path=template_path, env_vars=env_vars
+        cmd_res = self._deploy_compose_service(
+            project=name,
+            template_paths=[template_path, twilio_shim_path],
+            env_file=env_file,
         )
 
         # Deploy mail server (mailpit)
@@ -216,9 +238,7 @@ def deploy_appwrite_lab(
             / "mailpit"
             / "docker_compose.yml"
         )
-        self._deploy_service(
-            project=name, template_path=mailpit_template_path, env_vars={}
-        )
+        self._deploy_compose_service(project=name, template_paths=mailpit_template_path)
         # if CLI, will throw error in actual Response object
         if type(cmd_res) is Response and cmd_res.error:
             return cmd_res
@@ -246,6 +266,8 @@ def deploy_appwrite_lab(
             version=version,
             url=url,
             **_kwargs,
+            sms_shim_url="https://localhost:4443",
+            mailpit_url="http://localhost:8025",
         )
 
         lab.generate_missing_config()

appwrite_lab/_state.py

@@ -1,6 +1,5 @@
 import json
 import os
-from pathlib import Path
 
 from .utils import get_state_path
 

appwrite_lab/labs.py

@@ -152,7 +152,7 @@ def create_api_key(
         return Response(
             message=f"API key created for {project_name}",
             data=api_key.data,
-            _print_data=True,
+            _print_data=False,
         )
 
     def stop(self, name: str):

appwrite_lab/models.py

@@ -51,6 +51,8 @@ class Lab(_BaseClass):
         default_factory=lambda: {"default": Project(None, None, None)}
     )
     _file: str = field(default="")
+    sms_shim_url: str = field(default="")
+    mailpit_url: str = field(default="")
 
     def generate_missing_config(self):
         """Generate missing data config with random values."""

appwrite_lab/templates/environment/dotenv

@@ -55,8 +55,8 @@ _APP_SMTP_PORT=1025
 _APP_SMTP_SECURE=
 _APP_SMTP_USERNAME=
 _APP_SMTP_PASSWORD=
-_APP_SMS_PROVIDER=
-_APP_SMS_FROM=
+_APP_SMS_PROVIDER=sms://twilio:shim@twilio
+_APP_SMS_FROM=+15555555555
 _APP_STORAGE_LIMIT=30000000
 _APP_STORAGE_PREVIEW_LIMIT=20000000
 _APP_STORAGE_ANTIVIRUS=disabled

appwrite_lab/templates/extras/twilio-shim/docker_compose.yml

@@ -0,0 +1,61 @@
+x-sms-env: &sms_env
+  _APP_SMS_PROVIDER: ${_APP_SMS_PROVIDER:-sms://twilio:shim@twilio}
+  _APP_SMS_FROM:     ${_APP_SMS_FROM:-+15555555555}
+
+networks:
+  appwrite:
+    name: appwrite
+
+volumes:
+  fake_twilio_certs: {}
+  php_extra_conf: {}
+
+services:
+  # one-shot: write php ini into the named volume
+  php-ini-init:
+    image: busybox:1.36
+    volumes:
+      - php_extra_conf:/out
+    command: >
+      sh -lc 'printf "%s\n%s\n"
+      "curl.cainfo=/usr/local/share/ca-certificates/dev-rootCA.pem"
+      "openssl.cafile=/usr/local/share/ca-certificates/dev-rootCA.pem"
+      > /out/zz-dev-ca.ini'
+
+  twilio-shim:
+    image: syntaxsdev/twilio-shim:latest
+    volumes:
+      - fake_twilio_certs:/certs
+    ports: ["4443:443"]  # dev-only host access
+    networks:
+      appwrite:
+        aliases: [api.twilio.com]
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD","curl","-k","https://localhost:443/"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  appwrite:
+    depends_on:
+      php-ini-init: { condition: service_completed_successfully }
+    environment:
+      <<: *sms_env
+      PHP_INI_SCAN_DIR: /usr/local/etc/php/conf.d:/opt/php-extra-conf.d
+    volumes:
+      - fake_twilio_certs:/usr/local/share/ca-certificates:ro
+      - php_extra_conf:/opt/php-extra-conf.d:ro
+    networks: [appwrite]
+
+  appwrite-worker-messaging:
+    depends_on:
+      php-ini-init: { condition: service_completed_successfully }
+      twilio-shim:  { condition: service_healthy }
+    environment:
+      <<: *sms_env
+      PHP_INI_SCAN_DIR: /usr/local/etc/php/conf.d:/opt/php-extra-conf.d
+    volumes:
+      - fake_twilio_certs:/usr/local/share/ca-certificates:ro
+      - php_extra_conf:/opt/php-extra-conf.d:ro
+    networks: [appwrite]

appwrite_lab/tools/sms.py

@@ -0,0 +1,17 @@
+from appwrite_lab.models import Lab
+from httpx import AsyncClient
+
+
+class SMS:
+    def __init__(self, lab: Lab):
+        self.url = lab.sms_shim_url
+
+    async def get_messages(self):
+        async with AsyncClient(verify=False) as client:
+            response = await client.get(f"{self.url}/inbox")
+            return response.json().get("messages")
+
+    async def clear_messages(self):
+        async with AsyncClient(verify=False) as client:
+            response = await client.post(f"{self.url}/clear")
+            return response.json().get("ok")

pyproject.toml

@@ -4,11 +4,18 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "appwrite-lab"
-version = "0.1.2"
+version = "0.1.3"
 description = "Zero-click Appwrite test environments."
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = ["playwright", "typer>=0.16.0", "python-dotenv>=1.1.0", "pytest>=8.4.1"]
+dependencies = [
+    "playwright",
+    "typer>=0.16.0",
+    "python-dotenv>=1.1.0",
+    "pytest>=8.4.1",
+    "httpx>=0.28.1",
+    "pytest-asyncio>=1.1.0",
+]
 license = "MIT"
 
 [tool.setuptools]
@@ -23,6 +30,5 @@ appwrite-lab = "appwrite_lab.cli.entry:app"
 awlab = "appwrite_lab.cli.entry:app"
 
 [tool.pytest.ini_options]
-markers = [
-    "e2e: mark test as e2e",
-]
+markers = ["e2e: mark test as e2e"]
+asyncio_mode = "auto"

tests/conftest.py

@@ -2,9 +2,20 @@
 from pathlib import Path
 from appwrite_lab.models import Lab
 from appwrite_lab.test_suite import lab_svc, appwrite_file, lab_config, lab
+from appwrite_lab.tools.sms import SMS
 
 
 @pytest.fixture(scope="session")
 def appwrite_file_path():
     return Path(__file__).parent / "data" / "appwrite.json"
-    
+
+
+@pytest.fixture(scope="session")
+def sms(lab: Lab):
+    return SMS(lab)
+
+
+@pytest.fixture(autouse=True)
+async def clear_sms(sms: SMS):
+    yield
+    await sms.clear_messages()