Refactored test framework

.pre-commit-config.yaml

@@ -260,6 +260,7 @@ repos:
     hooks:
       - id: interrogate
         name: "📝 docs · Check docstring coverage"
+        exclude: ^(tests)
         args: [ --verbose, --fail-under=53, --ignore-init-method ]
 
   # Python type checking

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all clean clean-env clean-test clean-pyc clean-build clean-other help dev test test-debug test-cov pre-commit lint format format-docs analyze docs
+.PHONY: all clean clean-env clean-test clean-pyc clean-build clean-other help dev test test-unit test-integration test-debug test-cov tests-cov-fail pre-commit lint format format-docs analyze docs
 .DEFAULT_GOAL := help
 
 # The `.ONESHELL` and setting `SHELL` allows us to run commands that require
@@ -89,7 +89,7 @@ environment:	## handles environment creation
 	conda run --name $(CONDA_ENV_NAME) pip install .
 
 environment-dev:	## Handles environment creation
-	conda env create -n $(CONDA_ENV_NAME)-dev -y --file environment-dev.yml
+	conda env create -n $(CONDA_ENV_NAME)-dev -y --file environment-dev.yaml
 	conda run --name $(CONDA_ENV_NAME)-dev pip install -e .
 
 install: clean	## install the package to the active Python's site-packages
@@ -128,21 +128,27 @@ check-env:
 	  exit 1; \
 	fi
 
-test: check-env		## runs test cases
-	$(PYTHON3) -m pytest -v --capture=no $(TEST_DIR)/tests.py
+test: test-unit
 
-test-debug: check-env		## runs test cases with debugging info enabled
-	$(PYTHON3) -m pytest -vv --capture=no $(TEST_DIR)/tests.py
+test-unit:		## run unit tests only (no API key required)
+	$(PYTHON3) -m pytest -v --capture=no $(TEST_DIR)/unit/
 
-test-cov: check-env		## checks test coverage requirements
+test-integration: check-env		## run integration tests only (requires APIKEY and DOMAIN)
+	$(PYTHON3) -m pytest -v --capture=no $(TEST_DIR)/integration/
+
+test-debug:		## run unit tests with debugging info
+	$(PYTHON3) -m pytest -vv --capture=no $(TEST_DIR)/unit/
+
+test-cov:		## check test coverage (unit tests only)
 	$(PYTHON3) -m pytest --cov-config=.coveragerc --cov=$(SRC_DIR) \
-		$(TEST_DIR)/tests.py --cov-fail-under=80 --cov-report term-missing
+		$(TEST_DIR)/unit/ --cov-report term-missing
 
-tests-cov-fail:
-	@pytest --cov=$(SRC_DIR) --cov-report term-missing --cov-report=html --cov-fail-under=80
+test-cov-fail:		## check test coverage with fail-under (unit tests only)
+	$(PYTHON3) -m pytest --cov-config=.coveragerc --cov=$(SRC_DIR) \
+		$(TEST_DIR)/unit/ --cov-fail-under=80 --cov-report term-missing --cov-report=html
 
-coverage:	## check code coverage quickly with the default Python
-	coverage run --source $(SRC_DIR) -m pytest
+coverage:	## check code coverage quickly with the default Python (unit tests only)
+	coverage run --source $(SRC_DIR) -m pytest $(TEST_DIR)/unit/
 	coverage report -m
 	coverage html
 	$(BROWSER) htmlcov/index.html

tests/integration/__init__.py

@@ -0,0 +1 @@
+"""Integration tests for the Mailgun API client."""

tests/unit/__init__.py

@@ -0,0 +1 @@
+"""Unit tests for the Mailgun API client."""

tests/unit/test_async_client.py

@@ -0,0 +1,144 @@
+"""Unit tests for mailgun.client (AsyncClient, AsyncEndpoint)."""
+
+import io
+from unittest.mock import AsyncMock
+from unittest.mock import MagicMock
+
+import httpx
+import pytest
+
+from mailgun.client import AsyncClient
+from mailgun.client import AsyncEndpoint
+from mailgun.client import Config
+from mailgun.handlers.error_handler import ApiError
+
+
+class TestAsyncEndpointPrepareFiles:
+    """Tests for AsyncEndpoint._prepare_files."""
+
+    def _make_endpoint(self) -> AsyncEndpoint:
+        url = {"base": "https://api.mailgun.net/v3/", "keys": ["messages"]}
+        return AsyncEndpoint(
+            url=url,
+            headers={},
+            auth=None,
+            client=MagicMock(spec=httpx.AsyncClient),
+        )
+
+    def test_prepare_files_none(self) -> None:
+        ep = self._make_endpoint()
+        assert ep._prepare_files(None) is None
+
+    def test_prepare_files_dict_bytes(self) -> None:
+        ep = self._make_endpoint()
+        files = {"attachment": b"binary content"}
+        result = ep._prepare_files(files)
+        assert result is not None
+        assert "attachment" in result
+        # (filename, file_obj, content_type)
+        assert len(result["attachment"]) == 3
+        assert result["attachment"][0] == "attachment"
+        assert isinstance(result["attachment"][1], io.BytesIO)
+        assert result["attachment"][1].read() == b"binary content"
+        assert result["attachment"][2] == "application/octet-stream"
+
+    def test_prepare_files_dict_tuple(self) -> None:
+        ep = self._make_endpoint()
+        files = {"f": ("name.txt", b"data", "text/plain")}
+        result = ep._prepare_files(files)
+        assert result is not None
+        assert result["f"][0] == "name.txt"
+        assert result["f"][2] == "text/plain"
+
+
+class TestAsyncEndpoint:
+    """Tests for AsyncEndpoint with mocked httpx."""
+
+    @pytest.mark.asyncio
+    async def test_get_calls_client_request(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        mock_client = AsyncMock(spec=httpx.AsyncClient)
+        mock_client.request = AsyncMock(
+            return_value=MagicMock(status_code=200, spec=httpx.Response)
+        )
+        ep = AsyncEndpoint(url=url, headers={"User-agent": "test"}, auth=("api", "key"), client=mock_client)
+        await ep.get()
+        mock_client.request.assert_called_once()
+        assert mock_client.request.call_args[1]["method"] == "GET"
+
+    @pytest.mark.asyncio
+    async def test_create_sends_post(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        mock_client = AsyncMock(spec=httpx.AsyncClient)
+        mock_client.request = AsyncMock(
+            return_value=MagicMock(status_code=200, spec=httpx.Response)
+        )
+        ep = AsyncEndpoint(url=url, headers={}, auth=None, client=mock_client)
+        await ep.create(data={"name": "test.com"})
+        mock_client.request.assert_called_once()
+        assert mock_client.request.call_args[1]["method"] == "POST"
+
+    @pytest.mark.asyncio
+    async def test_delete_calls_client_request(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        mock_client = AsyncMock(spec=httpx.AsyncClient)
+        mock_client.request = AsyncMock(
+            return_value=MagicMock(status_code=200, spec=httpx.Response)
+        )
+        ep = AsyncEndpoint(url=url, headers={}, auth=None, client=mock_client)
+        await ep.delete()
+        assert mock_client.request.call_args[1]["method"] == "DELETE"
+
+    @pytest.mark.asyncio
+    async def test_api_call_raises_timeout_error(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        mock_client = AsyncMock(spec=httpx.AsyncClient)
+        mock_client.request = AsyncMock(side_effect=httpx.TimeoutException("timeout"))
+        ep = AsyncEndpoint(url=url, headers={}, auth=None, client=mock_client)
+        with pytest.raises(TimeoutError):
+            await ep.get()
+
+    @pytest.mark.asyncio
+    async def test_api_call_raises_api_error_on_request_error(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        mock_client = AsyncMock(spec=httpx.AsyncClient)
+        mock_client.request = AsyncMock(side_effect=httpx.RequestError("error"))
+        ep = AsyncEndpoint(url=url, headers={}, auth=None, client=mock_client)
+        with pytest.raises(ApiError):
+            await ep.get()
+
+
+class TestAsyncClient:
+    """Tests for AsyncClient."""
+
+    def test_async_client_inherits_client(self) -> None:
+        client = AsyncClient(auth=("api", "key"))
+        assert isinstance(client, AsyncClient)
+        assert client.auth == ("api", "key")
+        assert client.config.api_url == Config.DEFAULT_API_URL
+
+    def test_async_client_getattr_returns_async_endpoint_type(self) -> None:
+        client = AsyncClient(auth=("api", "key"))
+        ep = client.domains
+        assert ep is not None
+        assert isinstance(ep, AsyncEndpoint)
+        assert type(ep).__name__ == "domains"
+
+    @pytest.mark.asyncio
+    async def test_aclose_closes_httpx_client(self) -> None:
+        client = AsyncClient(auth=("api", "key"))
+        # Trigger _client creation
+        _ = client.domains
+        assert client._httpx_client is None or not client._httpx_client.is_closed
+        # Access property to create client
+        _ = client._client
+        await client.aclose()
+        assert client._httpx_client.is_closed
+
+    @pytest.mark.asyncio
+    async def test_async_context_manager(self) -> None:
+        async with AsyncClient(auth=("api", "key")) as client:
+            assert client is not None
+            assert isinstance(client, AsyncClient)
+        # After exit, client should be closed
+        assert client._httpx_client is None or client._httpx_client.is_closed

tests/unit/test_client.py

@@ -0,0 +1,157 @@
+"""Unit tests for mailgun.client (Client, Config, Endpoint)."""
+
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import pytest
+import requests
+
+from mailgun.client import BaseEndpoint
+from mailgun.client import Client
+from mailgun.client import Config
+from mailgun.client import Endpoint
+from mailgun.handlers.error_handler import ApiError
+
+
+class TestClient:
+    """Tests for Client class."""
+
+    def test_client_init_default(self) -> None:
+        client = Client()
+        assert client.auth is None
+        assert client.config.api_url == Config.DEFAULT_API_URL
+
+    def test_client_init_with_auth(self) -> None:
+        client = Client(auth=("api", "key-123"))
+        assert client.auth == ("api", "key-123")
+
+    def test_client_init_with_api_url(self) -> None:
+        client = Client(api_url="https://custom.api/")
+        assert client.config.api_url == "https://custom.api/"
+
+    def test_client_getattr_returns_endpoint_type(self) -> None:
+        client = Client(auth=("api", "key-123"))
+        ep = client.domains
+        assert ep is not None
+        assert isinstance(ep, Endpoint)
+        assert type(ep).__name__ == "domains"
+
+    def test_client_getattr_ips(self) -> None:
+        client = Client(auth=("api", "key-123"))
+        ep = client.ips
+        assert type(ep).__name__ == "ips"
+
+
+class TestBaseEndpointBuildUrl:
+    """Tests for BaseEndpoint.build_url (static, dispatches to handlers)."""
+
+    def test_build_url_domains_with_domain(self) -> None:
+        # With domain_name in kwargs, handle_domains includes it in the URL
+        url = {"base": "https://api.mailgun.net/v4/domains/", "keys": ["domains"]}
+        result = BaseEndpoint.build_url(
+            url, domain="example.com", method="get", domain_name="example.com"
+        )
+        assert "example.com" in result
+
+    def test_build_url_domainlist(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        result = BaseEndpoint.build_url(url, method="get")
+        assert "domains" in result
+
+    def test_build_url_default_requires_domain(self) -> None:
+        url = {"base": "https://api.mailgun.net/v3/", "keys": ["messages"]}
+        with pytest.raises(ApiError, match="Domain is missing"):
+            BaseEndpoint.build_url(url, method="post")
+
+
+class TestEndpoint:
+    """Tests for Endpoint (sync) with mocked HTTP."""
+
+    def test_get_calls_requests_get(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        headers = {"User-agent": "test"}
+        auth = ("api", "key-123")
+        ep = Endpoint(url=url, headers=headers, auth=auth)
+        with patch.object(requests, "get", return_value=MagicMock(status_code=200)) as m_get:
+            ep.get()
+            m_get.assert_called_once()
+            call_kw = m_get.call_args[1]
+            assert call_kw["auth"] == auth
+            assert call_kw["headers"] == headers
+            assert "domainlist" in m_get.call_args[0][0] or "domains" in m_get.call_args[0][0]
+
+    def test_get_with_filters(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=None)
+        with patch.object(requests, "get", return_value=MagicMock(status_code=200)) as m_get:
+            ep.get(filters={"limit": 10})
+            m_get.assert_called_once()
+            assert m_get.call_args[1]["params"] == {"limit": 10}
+
+    def test_create_sends_post(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=("api", "key"))
+        with patch.object(requests, "post", return_value=MagicMock(status_code=200)) as m_post:
+            ep.create(data={"name": "test.com"})
+            m_post.assert_called_once()
+            assert m_post.call_args[1]["data"] is not None
+
+    def test_create_json_serializes_when_content_type_json(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(
+            url=url,
+            headers={"Content-Type": "application/json"},
+            auth=None,
+        )
+        with patch.object(requests, "post", return_value=MagicMock(status_code=200)) as m_post:
+            ep.create(data={"name": "test.com"})
+            call_data = m_post.call_args[1]["data"]
+            assert call_data == '{"name": "test.com"}'
+
+    def test_delete_calls_requests_delete(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=None)
+        with patch.object(requests, "delete", return_value=MagicMock(status_code=200)) as m_del:
+            ep.delete()
+            m_del.assert_called_once()
+
+    def test_put_calls_requests_put(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=None)
+        with patch.object(requests, "put", return_value=MagicMock(status_code=200)) as m_put:
+            ep.put(data={"key": "value"})
+            m_put.assert_called_once()
+
+    def test_patch_calls_requests_patch(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=None)
+        with patch.object(requests, "patch", return_value=MagicMock(status_code=200)) as m_patch:
+            ep.patch(data={"key": "value"})
+            m_patch.assert_called_once()
+
+    def test_api_call_raises_timeout_error_on_timeout(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=None)
+        with patch.object(requests, "get", side_effect=requests.exceptions.Timeout()):
+            with pytest.raises(TimeoutError):
+                ep.get()
+
+    def test_api_call_raises_api_error_on_request_exception(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(url=url, headers={}, auth=None)
+        with patch.object(
+            requests, "get", side_effect=requests.exceptions.RequestException("network error")
+        ):
+            with pytest.raises(ApiError):
+                ep.get()
+
+    def test_update_serializes_json(self) -> None:
+        url = {"base": "https://api.mailgun.net/v4/", "keys": ["domainlist"]}
+        ep = Endpoint(
+            url=url,
+            headers={"Content-type": "application/json"},
+            auth=None,
+        )
+        with patch.object(requests, "put", return_value=MagicMock(status_code=200)) as m_put:
+            ep.update(data={"name": "updated.com"})
+            assert m_put.call_args[1]["data"] == '{"name": "updated.com"}'