provide-testkit 0.0.0.dev0__py3-none-any.whl

provide/testkit/cli.py

@@ -0,0 +1,229 @@
+"""
+CLI Testing Utilities for Foundation.
+
+Provides comprehensive testing support for CLI applications including
+context mocking, isolated runners, and configuration helpers.
+"""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import click
+from click.testing import CliRunner, Result
+import pytest
+
+from provide.foundation.context import CLIContext
+from provide.foundation.file import temp_file as foundation_temp_file
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class MockContext(CLIContext):
+    """Mock context for testing that tracks method calls."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize mock context with tracking."""
+        super().__init__(**kwargs)
+        self.calls = []
+        self.saved_configs = []
+        self.loaded_configs = []
+
+    def save_config(self, path: str | Path) -> None:
+        """Track save_config calls."""
+        self.saved_configs.append(path)
+        super().save_config(path)
+
+    def load_config(self, path: str | Path) -> None:
+        """Track load_config calls."""
+        self.loaded_configs.append(path)
+        super().load_config(path)
+
+
+@contextmanager
+def isolated_cli_runner(
+    env: dict[str, str] | None = None,
+) -> Generator[CliRunner, None, None]:
+    """
+    Create an isolated test environment for CLI testing.
+
+    Args:
+        env: Environment variables to set
+
+    Yields:
+        CliRunner instance in isolated filesystem
+    """
+    runner = CliRunner()
+
+    with runner.isolated_filesystem():
+        # Set up environment
+        old_env = {}
+        if env:
+            for key, value in env.items():
+                old_env[key] = os.environ.get(key)
+                os.environ[key] = value
+
+        try:
+            yield runner
+        finally:
+            # Restore environment
+            for key, old_value in old_env.items():
+                if old_value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = old_value
+
+
+@contextmanager
+def temp_config_file(
+    content: dict[str, Any] | str,
+    format: str = "json",
+) -> Path:
+    """
+    Create a temporary configuration file for testing.
+
+    Args:
+        content: Configuration content (dict or string)
+        format: File format (json, toml, yaml)
+
+    Yields:
+        Path to temporary config file
+    """
+    suffix = f".{format}"
+
+    with foundation_temp_file(suffix=suffix, text=True, cleanup=False) as config_path:
+        with open(config_path, "w") as f:
+            if isinstance(content, dict):
+                if format == "json":
+                    json.dump(content, f, indent=2)
+                elif format == "toml":
+                    try:
+                        import tomli_w
+
+                        # tomli_w needs the content as a string, not written to file handle
+                        toml_content = tomli_w.dumps(content)
+                        f.write(toml_content)
+                    except ImportError:
+                        # Fall back to manual formatting
+                        for key, value in content.items():
+                            if isinstance(value, str):
+                                f.write(f'{key} = "{value}"\n')
+                            elif isinstance(value, bool):
+                                # TOML uses lowercase for booleans
+                                f.write(f"{key} = {str(value).lower()}\n")
+                            else:
+                                f.write(f"{key} = {value}\n")
+                elif format == "yaml":
+                    try:
+                        import yaml
+
+                        yaml.safe_dump(content, f)
+                    except ImportError:
+                        raise ImportError("PyYAML required for YAML testing")
+            else:
+                f.write(content)
+
+    try:
+        yield config_path
+    finally:
+        config_path.unlink(missing_ok=True)
+
+
+def create_test_cli(
+    name: str = "test-cli",
+    version: str = "1.0.0",
+    commands: list[click.Command] | None = None,
+) -> click.Group:
+    """
+    Create a test CLI group with standard options.
+
+    Args:
+        name: CLI name
+        version: CLI version
+        commands: Optional list of commands to add
+
+    Returns:
+        Click Group configured for testing
+    """
+    from provide.foundation.cli.decorators import standard_options
+
+    @click.group(name=name)
+    @standard_options
+    @click.pass_context
+    def cli(ctx: click.Context, **kwargs: Any) -> None:
+        """Test CLI for testing."""
+        ctx.obj = CLIContext(**{k: v for k, v in kwargs.items() if v is not None})
+
+    if commands:
+        for cmd in commands:
+            cli.add_command(cmd)
+
+    return cli
+
+
+class CliTestCase:
+    """Base class for CLI test cases with common utilities."""
+
+    def setup_method(self) -> None:
+        """Set up test case."""
+        self.runner = CliRunner()
+        self.temp_files = []
+
+    def teardown_method(self) -> None:
+        """Clean up test case."""
+        for path in self.temp_files:
+            if path.exists():
+                path.unlink()
+
+    def invoke(self, *args: Any, **kwargs: Any) -> Result:
+        """Invoke CLI command."""
+        return self.runner.invoke(*args, **kwargs)
+
+    def create_temp_file(self, content: str = "", suffix: str = "") -> Path:
+        """Create a temporary file that will be cleaned up."""
+        with foundation_temp_file(suffix=suffix, text=True, cleanup=False) as path:
+            path.write_text(content)
+
+        self.temp_files.append(path)
+        return path
+
+    def assert_json_output(self, result: Result, expected: dict[str, Any]) -> None:
+        """Assert that output is valid JSON matching expected."""
+        try:
+            output = json.loads(result.output)
+        except json.JSONDecodeError as e:
+            raise AssertionError(f"Output is not valid JSON: {e}\n{result.output}")
+
+        for key, value in expected.items():
+            assert key in output, f"Key '{key}' not in output"
+            assert output[key] == value, f"Value mismatch for '{key}': {output[key]} != {value}"
+
+
+@pytest.fixture
+def click_testing_mode() -> Generator[None, None, None]:
+    """
+    Pytest fixture to enable Click testing mode.
+
+    Sets CLICK_TESTING=1 environment variable for the duration of the test,
+    then restores the original value. This fixture makes it easy to enable
+    Click testing mode without manual environment variable management.
+
+    Usage:
+        def test_my_cli(click_testing_mode):
+            # Test CLI code here - CLICK_TESTING is automatically set
+            pass
+    """
+    original_value = os.environ.get("CLICK_TESTING")
+    os.environ["CLICK_TESTING"] = "1"
+
+    try:
+        yield
+    finally:
+        if original_value is None:
+            os.environ.pop("CLICK_TESTING", None)
+        else:
+            os.environ["CLICK_TESTING"] = original_value

provide/testkit/common/__init__.py

@@ -0,0 +1,32 @@
+"""
+Common testing fixtures for the provide-io ecosystem.
+
+Standard mock objects and fixtures that are used across multiple modules
+in any project that depends on provide.foundation.
+"""
+
+from provide.testkit.common.fixtures import (
+    mock_cache,
+    mock_config_source,
+    mock_database,
+    mock_event_emitter,
+    mock_file_system,
+    mock_http_config,
+    mock_metrics_collector,
+    mock_subprocess,
+    mock_telemetry_config,
+    mock_transport,
+)
+
+__all__ = [
+    "mock_cache",
+    "mock_config_source",
+    "mock_database",
+    "mock_event_emitter",
+    "mock_file_system",
+    "mock_http_config",
+    "mock_metrics_collector",
+    "mock_subprocess",
+    "mock_telemetry_config",
+    "mock_transport",
+]

provide/testkit/common/fixtures.py

@@ -0,0 +1,234 @@
+"""
+Common Mock Objects and Fixtures.
+
+Reusable mock objects for configuration, logging, and other common
+testing scenarios across the provide-io ecosystem.
+"""
+
+from typing import Any
+from unittest.mock import Mock, PropertyMock
+
+import pytest
+
+from provide.foundation import TelemetryConfig
+from provide.foundation.logger.config.logging import LoggingConfig
+
+
+@pytest.fixture
+def mock_http_config() -> Any:
+    """
+    Standard HTTP configuration for testing.
+
+    Returns:
+        HTTPConfig with common test settings.
+    """
+    from provide.foundation.transport.config import HTTPConfig
+
+    return HTTPConfig(
+        timeout=30.0,
+        max_retries=3,
+        retry_backoff_factor=0.5,
+        verify_ssl=True,
+        pool_connections=10,
+        pool_maxsize=100,
+        follow_redirects=True,
+        http2=True,
+        max_redirects=5,
+    )
+
+
+@pytest.fixture
+def mock_telemetry_config() -> TelemetryConfig:
+    """
+    Standard telemetry configuration for testing.
+
+    Returns:
+        TelemetryConfig with debug logging enabled.
+    """
+    return TelemetryConfig(
+        logging=LoggingConfig(default_level="DEBUG"),
+        globally_disabled=False,
+        service_name="test_service",
+        service_version="1.0.0",
+    )
+
+
+@pytest.fixture
+def mock_config_source() -> Mock:
+    """
+    Mock configuration source for testing config loading.
+
+    Returns:
+        Mock that simulates a configuration source.
+    """
+    source = Mock()
+    source.load = Mock(return_value={"key": "value", "nested": {"key": "value"}})
+    source.exists = Mock(return_value=True)
+    source.reload = Mock()
+    source.watch = Mock()
+    source.priority = 100
+    source.name = "mock_source"
+
+    return source
+
+
+@pytest.fixture
+def mock_event_emitter():
+    """
+    Mock event emitter for testing event-driven components.
+
+    Returns:
+        Mock with emit, on, off methods.
+    """
+    emitter = Mock()
+    emitter.emit = Mock()
+    emitter.on = Mock()
+    emitter.off = Mock()
+    emitter.once = Mock()
+    emitter.listeners = Mock(return_value=[])
+    emitter.remove_all_listeners = Mock()
+
+    return emitter
+
+
+@pytest.fixture
+def mock_transport():
+    """
+    Mock transport for testing network operations.
+
+    Returns:
+        Mock transport with request/response methods.
+    """
+    transport = Mock()
+    transport.request = Mock(return_value={"status": 200, "data": {}})
+    transport.get = Mock(return_value={"status": 200, "data": {}})
+    transport.post = Mock(return_value={"status": 200, "data": {}})
+    transport.put = Mock(return_value={"status": 200, "data": {}})
+    transport.delete = Mock(return_value={"status": 204})
+    transport.close = Mock()
+
+    return transport
+
+
+@pytest.fixture
+def mock_metrics_collector():
+    """
+    Mock metrics collector for testing instrumentation.
+
+    Returns:
+        Mock with common metrics methods.
+    """
+    collector = Mock()
+    collector.increment = Mock()
+    collector.decrement = Mock()
+    collector.gauge = Mock()
+    collector.histogram = Mock()
+    collector.timer = Mock()
+    collector.flush = Mock()
+
+    # Add context manager support for timing
+    timer_cm = Mock()
+    timer_cm.__enter__ = Mock(return_value=timer_cm)
+    timer_cm.__exit__ = Mock(return_value=None)
+    collector.timer.return_value = timer_cm
+
+    return collector
+
+
+@pytest.fixture
+def mock_cache():
+    """
+    Mock cache for testing caching behavior.
+
+    Returns:
+        Mock with get, set, delete, clear methods.
+    """
+    cache_data = {}
+
+    cache = Mock()
+    cache.get = Mock(side_effect=lambda k, default=None: cache_data.get(k, default))
+    cache.set = Mock(side_effect=lambda k, v, ttl=None: cache_data.update({k: v}))
+    cache.delete = Mock(side_effect=lambda k: cache_data.pop(k, None))
+    cache.clear = Mock(side_effect=cache_data.clear)
+    cache.exists = Mock(side_effect=lambda k: k in cache_data)
+    cache.keys = Mock(return_value=list(cache_data.keys()))
+
+    # Store reference to data for test assertions
+    cache._data = cache_data
+
+    return cache
+
+
+@pytest.fixture
+def mock_database():
+    """
+    Mock database connection for testing.
+
+    Returns:
+        Mock with execute, fetch, commit, rollback methods.
+    """
+    db = Mock()
+    db.execute = Mock(return_value=Mock(rowcount=1))
+    db.fetch = Mock(return_value=[])
+    db.fetchone = Mock(return_value=None)
+    db.fetchall = Mock(return_value=[])
+    db.commit = Mock()
+    db.rollback = Mock()
+    db.close = Mock()
+    db.is_connected = PropertyMock(return_value=True)
+
+    # Add context manager support
+    db.__enter__ = Mock(return_value=db)
+    db.__exit__ = Mock(return_value=None)
+
+    return db
+
+
+@pytest.fixture
+def mock_file_system():
+    """
+    Mock file system operations.
+
+    Returns:
+        Mock with read, write, exists, delete methods.
+    """
+    fs = Mock()
+    fs.read = Mock(return_value=b"content")
+    fs.write = Mock()
+    fs.exists = Mock(return_value=True)
+    fs.delete = Mock()
+    fs.mkdir = Mock()
+    fs.rmdir = Mock()
+    fs.list = Mock(return_value=[])
+    fs.stat = Mock(return_value=Mock(st_size=1024, st_mtime=0))
+
+    return fs
+
+
+@pytest.fixture
+def mock_subprocess():
+    """
+    Mock subprocess for testing command execution.
+
+    Returns:
+        Mock with run, Popen methods.
+    """
+    subprocess = Mock()
+
+    # Mock run method
+    result = Mock()
+    result.returncode = 0
+    result.stdout = "output"
+    result.stderr = ""
+    subprocess.run = Mock(return_value=result)
+
+    # Mock Popen
+    process = Mock()
+    process.communicate = Mock(return_value=("output", ""))
+    process.returncode = 0
+    process.pid = 12345
+    process.poll = Mock(return_value=0)
+    process.wait = Mock(return_value=0)
+    subprocess.Popen = Mock(return_value=process)
+
+    return subprocess

provide/testkit/crypto.py

@@ -0,0 +1,163 @@
+"""
+Crypto Testing Fixtures for Foundation.
+
+Provides comprehensive pytest fixtures for testing certificate functionality,
+including valid/invalid certificates, keys, chains, and edge cases.
+"""
+
+import pytest
+
+from provide.foundation import logger
+from provide.foundation.crypto import Certificate
+
+
+@pytest.fixture(scope="module")
+def client_cert() -> Certificate:
+    """Create a client certificate for testing."""
+    cert_pem = """-----BEGIN CERTIFICATE-----
+MIIB+jCCAYGgAwIBAgIJAPsxOr78BIU0MAoGCCqGSM49BAMEMCgxEjAQBgNVBAoM
+CUhhc2hpQ29ycDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDIwNTIzMTkzN1oX
+DTI2MDIwNTIzMTkzN1owKDESMBAGA1UECgwJSGFzaGlDb3JwMRIwEAYDVQQDDAls
+b2NhbGhvc3QwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARCi3SNYYDpSeScRM52tFYr
+URzsPOE/ad8BzvpvL+mfy1c5oHQhh6KPnxpoo1WyDJGYplwPTGS68DvvWmolrPAt
+C7I7r7spgyJS1358E5fA2NWk9/YPaiUzK2gsyrL9dKajdzB1MA8GA1UdEwEB/wQF
+MAMBAf8wFAYDVR0RBA0wC4IJbG9jYWxob3N0MB0GA1UdJQQWMBQGCCsGAQUFBwMC
+BggrBgEFBQcDATAOBgNVHQ8BAf8EBAMCA6gwHQYDVR0OBBYEFOwuttXPh5kTPSpX
+a2ex0+VKjlpaMAoGCCqGSM49BAMEA2cAMGQCMGbN17Zt1GxZ41cXTaQOKuv/BIQd
+nkaRz51XrITKaULNie4bgW6gT94cTUFQ9SNwEAIwOpmKeZqYG9WHcqol4QEUmMVM
+MY3jxMiLpb9Mt/ysstXmsrQY7UoLu+c6zfKwyTEJ
+-----END CERTIFICATE-----"""
+
+    key_pem = """-----BEGIN EC PRIVATE KEY-----
+MIGkAgEBBDAkxo19KczdciRiJjOWEKGY5mH9s1D0aUS5XBdvktcaonIOdqNrkCt1
+BC5YjEAVLNWgBwYFK4EEACKhZANiAARCi3SNYYDpSeScRM52tFYrURzsPOE/ad8B
+zvpvL+mfy1c5oHQhh6KPnxpoo1WyDJGYplwPTGS68DvvWmolrPAtC7I7r7spgyJS
+1358E5fA2NWk9/YPaiUzK2gsyrL9dKY=
+-----END EC PRIVATE KEY-----"""
+
+    logger.debug(f"Created CLIENT_CERT fixture: {cert_pem[:30]}...")
+    return Certificate(cert_pem_or_uri=cert_pem, key_pem_or_uri=key_pem)
+
+
+@pytest.fixture(scope="module")
+def server_cert() -> Certificate:
+    """Create a server certificate for testing."""
+    cert_pem = """-----BEGIN CERTIFICATE-----
+MIIB+jCCAYGgAwIBAgIJAKrIoEQw7N9LMAoGCCqGSM49BAMEMCgxEjAQBgNVBAoM
+CUhhc2hpQ29ycDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDIwNTIzMTkzN1oX
+DTI2MDIwNTIzMTkzN1owKDESMBAGA1UECgwJSGFzaGlDb3JwMRIwEAYDVQQDDAls
+b2NhbGhvc3QwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARMxEVmGX3a4IWPOAJ2MX2s
+2Wj3KZ0Io5EwUPMkxknGheO2e55qeHp/tkEFzYt9AH8du1xJLKKFbsGV5q9vipGN
+x5XMbj2RMdH5VXHTAdc/bLFFy9kybQqo300Rv6ViW2KjdzB1MA8GA1UdEwEB/wQF
+MAMBAf8wFAYDVR0RBA0wC4IJbG9jYWxob3N0MB0GA1UdJQQWMBQGCCsGAQUFBwMC
+BggrBgEFBQcDATAOBgNVHQ8BAf8EBAMCA6gwHQYDVR0OBBYEFJy7Iz7whfiALYDB
+TsM+IHXb1E8+MAoGCCqGSM49BAMEA2cAMGQCMFwxBS3lZSUprvrNGfJL83oGVY97
+emQpHy/SEWpHBK8awn1XeTf+ZAwLaxc3K+AKqwIwPwIbIlmstd69zAYMFNHtzceN
+XOzBx35sWRw92gr/hbE4hYeDBqEUwstSFNZ6MZu0
+-----END CERTIFICATE-----"""
+
+    key_pem = """-----BEGIN EC PRIVATE KEY-----
+MIGkAgEBBDDZ1MORWFVI0HtgKv+zZys/5e1HVmfcs4bwdp3VEsuwS6an3gTwGnSP
+Ce+bI6f/TvGgBwYFK4EEACKhZANiAARMxEVmGX3a4IWPOAJ2MX2s2Wj3KZ0Io5Ew
+UPMkxknGheO2e55qeHp/tkEFzYt9AH8du1xJLKKFbsGV5q9vipGNx5XMbj2RMdH5
+VXHTAdc/bLFFy9kybQqo300Rv6ViW2I=
+-----END EC PRIVATE KEY-----"""
+
+    logger.debug(f"Created SERVER_CERT fixture: {cert_pem[:30]}...")
+    return Certificate(cert_pem_or_uri=cert_pem, key_pem_or_uri=key_pem)
+
+
+@pytest.fixture(scope="module")
+def ca_cert() -> Certificate:
+    """Create a self-signed CA certificate for testing."""
+    return Certificate.create_ca(
+        common_name="Test CA", organization_name="Test Organization", validity_days=365
+    )
+
+
+@pytest.fixture(scope="module")
+def valid_key_pem(client_cert: Certificate) -> str:
+    """Get a valid key PEM from the client cert fixture."""
+    return client_cert.key
+
+
+@pytest.fixture
+def valid_cert_pem(client_cert: Certificate) -> str:
+    """Get a valid certificate PEM from the client cert fixture."""
+    return client_cert.cert
+
+
+@pytest.fixture
+def invalid_key_pem() -> str:
+    """Returns an invalid PEM key."""
+    return "INVALID KEY DATA"
+
+
+@pytest.fixture
+def invalid_cert_pem() -> str:
+    """Returns an invalid PEM certificate."""
+    return "INVALID CERTIFICATE DATA"
+
+
+@pytest.fixture
+def malformed_cert_pem() -> str:
+    """Returns a PEM certificate with incorrect headers."""
+    return "-----BEGIN CERT-----\nMALFORMED DATA\n-----END CERT-----"
+
+
+@pytest.fixture
+def empty_cert() -> str:
+    """Returns an empty certificate string."""
+    return ""
+
+
+@pytest.fixture
+def temporary_cert_file(tmp_path, client_cert) -> str:
+    """Creates a temporary file containing the client certificate."""
+    cert_file = tmp_path / "client_cert.pem"
+    cert_file.write_text(client_cert.cert)
+    return f"file://{cert_file}"
+
+
+@pytest.fixture
+def temporary_key_file(tmp_path, client_cert) -> str:
+    """Creates a temporary file containing the client private key."""
+    key_file = tmp_path / "client_key.pem"
+    key_file.write_text(client_cert.key)
+    return f"file://{key_file}"
+
+
+@pytest.fixture
+def cert_with_windows_line_endings(client_cert) -> str:
+    """Returns a certificate PEM with Windows line endings."""
+    return client_cert.cert.replace("\n", "\r\n")
+
+
+@pytest.fixture
+def cert_with_utf8_bom(client_cert) -> str:
+    """Returns a certificate PEM with UTF-8 BOM."""
+    return "\ufeff" + client_cert.cert
+
+
+@pytest.fixture
+def cert_with_extra_whitespace(client_cert) -> str:
+    """Returns a certificate PEM with extra whitespace."""
+    return f"   {client_cert.cert}   \n\n  "
+
+
+@pytest.fixture(scope="module")
+def external_ca_pem() -> str:
+    """Provides an externally generated CA certificate PEM."""
+    return """-----BEGIN CERTIFICATE-----
+MIIB4TCCAYegAwIBAgIJAPZ9vcVfR8AdMAoGCCqGSM49BAMCMFExCzAJBgNVBAYT
+AlVTMQswCQYDVQQIDAJDQTEUMBIGA1UEBwwLU2FuIEZyYW5jaXNjbzEOMAwGA1UE
+CgwFTXlPcmcxEzARBgNVBAMMCkV4dGVybmFsIENBMB4XDTI0MDgwMjEwNTgwMVoX
+DTM0MDczMDEwNTgwMVowUTELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMREwDwYD
+VQQHDAhTYW5EaWVnbzEOMAwGA1UECgwFTXlPcmcxEzARBgNVBAMMCkV4dGVybmFs
+IENBMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEgyF5Y8upm+M3ZzO8P4n7q2sS+L4c
+mhl5XGg3vIOwFf7lG8XZCgJ6Xy4t1t8oD3zY0m9X8H8Z4YhY7K6b7c8Y7Xv6Y9fV
+Q8M7Jg9nJ0x5c1N40zQwZzKjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E
+BTADAQH/MB0GA1UdDgQWBBTGX00Gq7b09y/0C9eK0XgJp0mY7DAKBggqhkjOPQQD
+AgNJADBGAiEAx1xH/b83/u5t7r29a/THZnFjQ7pvT2N0L4hG4BgGgXACIQD02W2+
+MHB78ZWM+JOgikYj99qD6nLp0nkMyGmkSC7RYg==
+-----END CERTIFICATE-----"""