provide-testkit 0.0.0.dev6__tar.gz → 0.0.31__tar.gz

{provide_testkit-0.0.0.dev6 → provide_testkit-0.0.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: provide-testkit
-Version: 0.0.0.dev6
+Version: 0.0.31
 Summary: Testing utilities and fixtures for the provide ecosystem.
 Author-email: Tim Perkins <code@tim.life>
 Maintainer-email: "provide.io" <code@provide.io>
@@ -50,6 +50,8 @@ Requires-Dist: types-grpcio>=1.0.0.20250603; extra == "typecheck"
 Requires-Dist: types-toml>=0.10.8.20240310; extra == "typecheck"
 Requires-Dist: types-protobuf>=6.30.2.20250516; extra == "typecheck"
 Requires-Dist: types-click>=7.1.8; extra == "typecheck"
+Requires-Dist: types-pyyaml>=6.0.12.20250915; extra == "typecheck"
+Requires-Dist: types-psutil>=7.0.0.20250822; extra == "typecheck"
 Provides-Extra: advanced-testing
 Requires-Dist: hypothesis>=6.131.28; extra == "advanced-testing"
 Requires-Dist: freezegun>=1.5.1; extra == "advanced-testing"

provide_testkit-0.0.31/VERSION

@@ -0,0 +1 @@
+0.0.31

{provide_testkit-0.0.0.dev6 → provide_testkit-0.0.31}/pyproject.toml

@@ -75,6 +75,8 @@ typecheck = [
     "types-toml>=0.10.8.20240310",
     "types-protobuf>=6.30.2.20250516",
     "types-click>=7.1.8",
+    "types-pyyaml>=6.0.12.20250915",
+    "types-psutil>=7.0.0.20250822",
 ]
 
 # Property-based and advanced testing

{provide_testkit-0.0.0.dev6 → provide_testkit-0.0.31}/src/provide/testkit/__init__.py

@@ -12,10 +12,10 @@ Note: Testing information is displayed via pytest hooks in conftest.py
 
 from typing import Any
 
-# Mapping of attribute names to their modules
+# Mapping of attribute names to their modules for lazy loading.
 _LAZY_IMPORTS = {
     # CLI testing utilities
-    "cli": [
+    "cli.testing": [
         "MockContext",
         "isolated_cli_runner",
         "temp_config_file",
@@ -23,6 +23,12 @@ _LAZY_IMPORTS = {
         "CliTestCase",
         "click_testing_mode",
     ],
+    # CLI runner utilities
+    "cli.runner": [
+        "CliTestRunner",
+        "assert_cli_success",
+        "assert_cli_error",
+    ],
     # Logger testing utilities
     "logger": [
         "reset_foundation_setup_for_testing",
@@ -36,11 +42,21 @@ _LAZY_IMPORTS = {
         "suppress_loggers",
     ],
     # Stream testing utilities
-    "streams": ["set_log_stream_for_testing"],
-    # Fixture utilities
-    "fixtures": [
+    "streams.testing": ["set_log_stream_for_testing", "enable_file_logging_for_testing"],
+    # Common fixture utilities
+    "common.fixtures": [
         "captured_stderr_for_foundation",
         "setup_foundation_telemetry_for_test",
+        "mock_http_config",
+        "mock_telemetry_config",
+        "mock_config_source",
+        "mock_event_emitter",
+        "mock_transport",
+        "mock_metrics_collector",
+        "mock_cache",
+        "mock_database",
+        "mock_file_system",
+        "mock_subprocess",
     ],
     # File testing utilities
     "file.fixtures": [
@@ -63,20 +79,6 @@ _LAZY_IMPORTS = {
         "async_iterator",
         "async_queue",
         "async_lock",
-        "mock_async_sleep",
-    ],
-    # Common mock utilities
-    "common.fixtures": [
-        "mock_http_config",
-        "mock_telemetry_config",
-        "mock_config_source",
-        "mock_event_emitter",
-        "mock_transport",
-        "mock_metrics_collector",
-        "mock_cache",
-        "mock_database",
-        "mock_file_system",
-        "mock_subprocess",
     ],
     # Transport/network testing utilities
     "transport.fixtures": [
@@ -100,7 +102,7 @@ _LAZY_IMPORTS = {
         "archive_stress_test_files",
     ],
     # Crypto fixtures
-    "crypto": [
+    "crypto.fixtures": [
         "client_cert",
         "server_cert",
         "ca_cert",
@@ -118,26 +120,95 @@ _LAZY_IMPORTS = {
         "external_ca_pem",
     ],
     # Hub fixtures
-    "hub": ["default_container_directory"],
+    "hub.fixtures": ["default_container_directory"],
     # Environment utilities
-    "environment": [
+    "utils.environment": [
         "TestEnvironment",
         "get_example_dir",
         "add_src_to_path",
         "reset_test_environment",
     ],
+    # Temp environment utilities
+    "utils.temp_env": [
+        "temp_env",
+        "temp_env_from_dict",
+        "isolated_env",
+        "EnvContext",
+    ],
+    # Base test classes
+    "base.foundation": [
+        "FoundationTestCase",
+    ],
+    "base.minimal": [
+        "MinimalTestCase",
+    ],
+    # Base harness utilities
+    "base.harness": [
+        "HarnessRunner",
+    ],
+    # Mocking utilities
+    "mocking.fixtures": [
+        "ANY",
+        "AsyncMock",
+        "MagicMock",
+        "Mock",
+        "PropertyMock",
+        "assert_mock_calls",
+        "async_mock_factory",
+        "auto_patch",
+        "call",
+        "magic_mock_factory",
+        "mock_factory",
+        "mock_open_fixture",
+        "patch",
+        "patch_fixture",
+        "patch_multiple_fixture",
+        "property_mock_factory",
+        "spy_fixture",
+    ],
+    # Time mocking utilities
+    "mocking.time": [
+        "SleepTracker",
+        "mock_sleep",
+        "mock_time_sleep",
+        "mock_asyncio_sleep",
+        "create_sleep_mock",
+    ],
+    # Time fixture utilities
+    "time.fixtures": [
+        "time_machine",
+        "freeze_time",
+        "mock_datetime",
+        "timer",
+        "time_travel",
+        "rate_limiter_mock",
+        "benchmark_timer",
+        "advance_time",
+    ],
+    # File temp utilities
+    "file.temp": [
+        "TempFileManager",
+        "create_temp_file",
+        "create_temp_dir",
+    ],
 }
 
 # Submodules that can be imported directly
 _DIRECT_SUBMODULES = [
     "archive",
+    "base",
+    "cli",
     "common",
+    "crypto",
     "file",
-    "process",
-    "transport",
+    "hub",
     "mocking",
-    "time",
+    "process",
+    "streams",
     "threading",
+    "time",
+    "transport",
+    "utils",
 ]
 
 
@@ -174,43 +245,11 @@ def __getattr__(name: str) -> Any:
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
 
-# Public API - these will be available for import but loaded lazily
-__all__ = [
-    "DEFAULT_NOISY_LOGGERS",
-    "CliTestCase",
-    "MockContext",
-    "TestEnvironment",
-    "_is_testing_context",
-    "add_src_to_path",
-    "ca_cert",
-    "captured_stderr_for_foundation",
-    "cert_with_extra_whitespace",
-    "cert_with_utf8_bom",
-    "cert_with_windows_line_endings",
-    "client_cert",
-    "create_test_cli",
-    "default_container_directory",
-    "empty_cert",
-    "external_ca_pem",
-    "get_example_dir",
-    "get_log_level_for_noisy_loggers",
-    "get_noisy_loggers",
-    "invalid_cert_pem",
-    "invalid_key_pem",
-    "isolated_cli_runner",
-    "malformed_cert_pem",
-    "mock_logger",
-    "pytest_runtest_setup",
-    "reset_foundation_setup_for_testing",
-    "reset_foundation_state",
-    "reset_test_environment",
-    "server_cert",
-    "set_log_stream_for_testing",
-    "setup_foundation_telemetry_for_test",
-    "suppress_loggers",
-    "temp_config_file",
-    "temporary_cert_file",
-    "temporary_key_file",
-    "valid_cert_pem",
-    "valid_key_pem",
-]
+# --- Public API ---
+# This list is dynamically generated to be comprehensive and stay in sync
+# with the lazy loader, ensuring a complete and correct public API.
+_all_lazy_attributes: list[str] = []
+for _attributes in _LAZY_IMPORTS.values():
+    _all_lazy_attributes.extend(_attributes)
+
+__all__ = sorted(list(set(_all_lazy_attributes)))

provide_testkit-0.0.31/src/provide/testkit/base/foundation.py

@@ -0,0 +1,90 @@
+"""
+FoundationTestCase Base Class.
+
+Provides a common base class for all Foundation-based tests with
+standard utilities, automatic setup/cleanup, and common assertions.
+"""
+
+from __future__ import annotations
+
+from provide.testkit.base.minimal import MinimalTestCase
+from provide.testkit.logger import reset_foundation_setup_for_testing
+
+
+class FoundationTestCase(MinimalTestCase):
+    """Base test case for Foundation-based tests.
+
+    Provides common utilities for testing Foundation applications:
+    - Automatic Foundation reset between tests
+    - Temporary file/directory tracking and cleanup
+    - Mock tracking utilities
+    - Common assertion methods
+    - Output capture helpers
+    """
+
+    def setup_method(self) -> None:
+        """Set up test case with Foundation reset."""
+        # Check if this test/class is marked as timing_sensitive
+        if self._needs_full_reset():
+            reset_foundation_setup_for_testing()
+        else:
+            # For timing-sensitive tests, do minimal reset to prevent test interference
+            # but avoid full setup that could affect timing
+            self._minimal_state_reset()
+
+        # Always call parent setup for basic utilities
+        super().setup_method()
+
+    def _needs_full_reset(self) -> bool:
+        """Check if this test needs full Foundation reset.
+
+        Returns False if test/class is marked with timing_sensitive marker.
+        """
+        # Get the current test item from pytest's request fixture
+        # We need to be careful here as this runs during setup
+        try:
+            import inspect
+
+            # Get the test method
+            frame = inspect.currentframe()
+            while frame:
+                if frame.f_code.co_name.startswith("test_"):
+                    test_method = getattr(self, frame.f_code.co_name, None)
+                    if test_method and hasattr(test_method, "pytestmark"):
+                        marks = getattr(test_method, "pytestmark", [])
+                        for mark in marks:
+                            if mark.name == "timing_sensitive":
+                                return False
+                    break
+                frame = frame.f_back
+
+            # Check class-level markers
+            if hasattr(self.__class__, "pytestmark"):
+                marks = getattr(self.__class__, "pytestmark", [])
+                for mark in marks:
+                    if mark.name == "timing_sensitive":
+                        return False
+        except Exception:
+            # If we can't determine, default to full reset for safety
+            pass
+
+        return True
+
+    def _minimal_state_reset(self) -> None:
+        """Perform minimal state reset for timing-sensitive tests.
+
+        This resets only the most critical global state that can cause
+        test interference, while avoiding expensive operations that could
+        affect timing.
+        """
+        try:
+            # Reset Hub state which includes component registry
+            from provide.foundation.testmode.internal import reset_hub_state
+
+            reset_hub_state()
+        except ImportError:
+            # Testmode module not available, skip
+            pass
+
+
+__all__ = ["FoundationTestCase"]

provide_testkit-0.0.31/src/provide/testkit/base/minimal.py

@@ -0,0 +1,122 @@
+"""
+MinimalTestCase Base Class.
+
+Provides a lightweight base class for tests that need common utilities
+but don't require Foundation state reset. Ideal for timing-sensitive
+tests or tests that don't use Foundation components.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from unittest.mock import Mock
+
+
+class MinimalTestCase:
+    """Minimal test case base class without Foundation reset overhead.
+
+    Provides common test utilities without the heavyweight Foundation reset:
+    - Temporary file/directory tracking and cleanup
+    - Mock tracking utilities
+    - Common assertion methods
+    - Output capture helpers
+
+    Use this for timing-sensitive tests or tests that don't need
+    Foundation state isolation.
+    """
+
+    def setup_method(self) -> None:
+        """Set up test case with minimal overhead."""
+        self._temp_files: list[Path] = []
+        self._mocks: list[Mock] = []
+
+    def teardown_method(self) -> None:
+        """Clean up test case."""
+        # Clean up temporary files
+        for path in self._temp_files:
+            if path.exists():
+                if path.is_file():
+                    path.unlink()
+                elif path.is_dir():
+                    import shutil
+
+                    shutil.rmtree(path)
+
+        # Reset mocks
+        for mock in self._mocks:
+            mock.reset_mock()
+
+    def create_temp_file(self, content: str = "", suffix: str = "") -> Path:
+        """Create a temporary file that will be cleaned up."""
+        from provide.foundation.file import temp_file
+
+        with temp_file(suffix=suffix, text=True, cleanup=False) as path:
+            if content:
+                path.write_text(content)
+            self._temp_files.append(path)
+            return path
+
+    def create_temp_dir(self) -> Path:
+        """Create a temporary directory that will be cleaned up."""
+        import tempfile
+
+        temp_dir = Path(tempfile.mkdtemp())
+        self._temp_files.append(temp_dir)
+        return temp_dir
+
+    def track_mock(self, mock: Mock) -> Mock:
+        """Track a mock for automatic reset during teardown."""
+        self._mocks.append(mock)
+        return mock
+
+    def assert_json_output(self, output: str, expected: dict[str, Any]) -> None:
+        """Assert that output is valid JSON matching expected values."""
+        try:
+            actual = json.loads(output)
+        except json.JSONDecodeError as e:
+            raise AssertionError(f"Output is not valid JSON: {e}\n{output}") from e
+
+        for key, value in expected.items():
+            assert key in actual, f"Key '{key}' not in output"
+            assert actual[key] == value, f"Value mismatch for '{key}': {actual[key]} != {value}"
+
+    def assert_contains_error(
+        self, output: str, error_type: type[Exception], message: str | None = None
+    ) -> None:
+        """Assert that output contains an error of the specified type."""
+        error_name = error_type.__name__
+        assert error_name in output, f"Error type '{error_name}' not found in output: {output}"
+
+        if message:
+            assert message in output, f"Error message '{message}' not found in output: {output}"
+
+    def assert_log_contains(self, captured_logs: str, level: str, message: str) -> None:
+        """Assert that captured logs contain a message at the specified level."""
+        log_line = f"[{level.lower()}]"
+        assert log_line in captured_logs, f"Log level '{level}' not found in logs"
+        assert message in captured_logs, f"Log message '{message}' not found in logs"
+
+    def assert_file_exists(self, path: str | Path) -> None:
+        """Assert that a file exists."""
+        file_path = Path(path)
+        assert file_path.exists(), f"File does not exist: {file_path}"
+        assert file_path.is_file(), f"Path exists but is not a file: {file_path}"
+
+    def assert_dir_exists(self, path: str | Path) -> None:
+        """Assert that a directory exists."""
+        dir_path = Path(path)
+        assert dir_path.exists(), f"Directory does not exist: {dir_path}"
+        assert dir_path.is_dir(), f"Path exists but is not a directory: {dir_path}"
+
+    def assert_output_contains(self, output: str, expected: str) -> None:
+        """Assert that output contains expected string."""
+        assert expected in output, f"Expected '{expected}' not found in output: {output}"
+
+    def assert_output_not_contains(self, output: str, unexpected: str) -> None:
+        """Assert that output does not contain unexpected string."""
+        assert unexpected not in output, f"Unexpected '{unexpected}' found in output: {output}"
+
+
+__all__ = ["MinimalTestCase"]

provide_testkit-0.0.31/src/provide/testkit/chaos/__init__.py

@@ -0,0 +1,103 @@
+"""Chaos testing utilities for property-based testing with Hypothesis.
+
+This module provides reusable Hypothesis strategies and fixtures for chaos engineering
+in tests. It enables systematic exploration of edge cases, race conditions, and failure
+scenarios that are difficult to test with traditional methods.
+
+Key Features:
+    - Property-based testing strategies for common chaos patterns
+    - Time manipulation and clock skew simulation
+    - Concurrency and race condition triggers
+    - I/O failure injection patterns
+    - Reusable pytest fixtures for chaos testing
+
+Example:
+    ```python
+    from hypothesis import given
+    from provide.testkit.chaos import chaos_timings, failure_patterns
+
+    @given(
+        timing=chaos_timings(),
+        failures=failure_patterns()
+    )
+    async def test_with_chaos(timing, failures):
+        # Your chaos test here
+        pass
+    ```
+"""
+
+from __future__ import annotations
+
+from provide.testkit.chaos.concurrency_strategies import (
+    async_event_patterns,
+    deadlock_scenarios,
+    lock_contention_patterns,
+    pid_recycling_scenarios,
+    process_pool_patterns,
+    race_condition_triggers,
+    task_cancellation_patterns,
+    thread_counts,
+)
+from provide.testkit.chaos.io_strategies import (
+    buffer_overflow_patterns,
+    disk_full_scenarios,
+    file_corruption_patterns,
+    file_sizes,
+    lock_file_scenarios,
+    network_error_patterns,
+    path_traversal_patterns,
+    permission_patterns,
+)
+from provide.testkit.chaos.strategies import (
+    chaos_timings,
+    edge_values,
+    failure_patterns,
+    malformed_inputs,
+    resource_limits,
+    unicode_chaos,
+)
+from provide.testkit.chaos.time_strategies import (
+    clock_skew,
+    deadline_scenarios,
+    jitter_patterns,
+    rate_burst_patterns,
+    retry_backoff_patterns,
+    time_advances,
+    timeout_patterns,
+)
+
+__all__ = [
+    # Concurrency strategies
+    "async_event_patterns",
+    # I/O strategies
+    "buffer_overflow_patterns",
+    # Core strategies
+    "chaos_timings",
+    # Time strategies
+    "clock_skew",
+    "deadline_scenarios",
+    "deadlock_scenarios",
+    "disk_full_scenarios",
+    "edge_values",
+    "failure_patterns",
+    "file_corruption_patterns",
+    "file_sizes",
+    "jitter_patterns",
+    "lock_contention_patterns",
+    "lock_file_scenarios",
+    "malformed_inputs",
+    "network_error_patterns",
+    "path_traversal_patterns",
+    "permission_patterns",
+    "pid_recycling_scenarios",
+    "process_pool_patterns",
+    "race_condition_triggers",
+    "rate_burst_patterns",
+    "resource_limits",
+    "retry_backoff_patterns",
+    "task_cancellation_patterns",
+    "thread_counts",
+    "time_advances",
+    "timeout_patterns",
+    "unicode_chaos",
+]