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

provide/testkit/environment.py

@@ -0,0 +1,79 @@
+"""
+Environment management utilities for testing.
+
+Provides context managers and utilities for managing test environments,
+environment variables, and foundation setup/cleanup.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from provide.testkit.logger import reset_foundation_setup_for_testing
+
+
+class TestEnvironment:
+    """Context manager for test environment setup with proper cleanup."""
+
+    def __init__(self, env_vars: dict[str, str] | None = None):
+        """
+        Initialize test environment manager.
+
+        Args:
+            env_vars: Dictionary of environment variables to set during the test
+        """
+        self.env_vars = env_vars or {}
+        self.original_env: dict[str, str | None] = {}
+
+    def __enter__(self) -> "TestEnvironment":
+        """Enter the test environment context."""
+        # Save original environment variables
+        for key in self.env_vars:
+            self.original_env[key] = os.environ.get(key)
+            os.environ[key] = self.env_vars[key]
+
+        # Reset foundation setup
+        reset_foundation_setup_for_testing()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit the test environment context and restore original state."""
+        # Restore original environment variables
+        for key, original_value in self.original_env.items():
+            if original_value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = original_value
+
+        # Reset foundation setup again for cleanup
+        reset_foundation_setup_for_testing()
+
+
+def get_example_dir() -> Path:
+    """Get the examples directory path consistently across examples."""
+    # Note: This assumes foundation project structure
+    # In testkit context, this should point to foundation's examples
+    current_file = Path(__file__).resolve()
+    # Go up from testkit/src/provide/testkit/environment.py to find foundation
+    testkit_root = current_file.parent.parent.parent.parent
+    foundation_root = testkit_root.parent / "provide-foundation"
+    return foundation_root / "examples"
+
+
+def add_src_to_path() -> Path:
+    """Add src directory to Python path for examples. Returns project root path."""
+    import sys
+
+    example_dir = get_example_dir()
+    project_root = example_dir.parent
+    src_path = project_root / "src"
+
+    if src_path.exists() and str(src_path) not in sys.path:
+        sys.path.insert(0, str(src_path))
+
+    return project_root
+
+
+def reset_test_environment() -> None:
+    """Reset the test environment to a clean state."""
+    reset_foundation_setup_for_testing()

provide/testkit/file/__init__.py

@@ -0,0 +1,40 @@
+"""
+File testing fixtures for the provide-io ecosystem.
+
+Standard fixtures for file and directory operations that can be used
+across any project that depends on provide.foundation.
+"""
+
+from provide.testkit.file.fixtures import (
+    binary_file,
+    empty_directory,
+    nested_directory_structure,
+    readonly_file,
+    temp_binary_file,
+    temp_csv_file,
+    temp_directory,
+    temp_executable_file,
+    temp_file,
+    temp_file_with_content,
+    temp_json_file,
+    temp_named_file,
+    temp_symlink,
+    test_files_structure,
+)
+
+__all__ = [
+    "binary_file",
+    "empty_directory",
+    "nested_directory_structure",
+    "readonly_file",
+    "temp_binary_file",
+    "temp_csv_file",
+    "temp_directory",
+    "temp_executable_file",
+    "temp_file",
+    "temp_file_with_content",
+    "temp_json_file",
+    "temp_named_file",
+    "temp_symlink",
+    "test_files_structure",
+]

provide/testkit/file/content_fixtures.py

@@ -0,0 +1,275 @@
+"""
+Content-based file test fixtures.
+
+Fixtures for creating files with specific content types like text, binary,
+CSV, JSON, and other structured data.
+"""
+
+import csv
+import json
+from pathlib import Path
+import random
+
+import pytest
+
+from provide.foundation.file import temp_file as foundation_temp_file
+from provide.foundation.file.safe import safe_delete
+
+
+@pytest.fixture
+def temp_file():
+    """
+    Create a temporary file factory with optional content.
+
+    Returns:
+        A function that creates temporary files with specified content and suffix.
+    """
+    created_files = []
+
+    def _make_temp_file(content: str = "test content", suffix: str = ".txt") -> Path:
+        """
+        Create a temporary file.
+
+        Args:
+            content: Content to write to the file
+            suffix: File suffix/extension
+
+        Returns:
+            Path to the created temporary file
+        """
+        with foundation_temp_file(suffix=suffix, text=True, cleanup=False) as path:
+            path.write_text(content)
+            created_files.append(path)
+            return path
+
+    yield _make_temp_file
+
+    # Cleanup all created files
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def temp_named_file():
+    """
+    Create a named temporary file factory.
+
+    Returns:
+        Function that creates named temporary files.
+    """
+    created_files = []
+
+    def _make_named_file(
+        content: bytes | str = None,
+        suffix: str = "",
+        prefix: str = "tmp",
+        dir: Path | str = None,
+        mode: str = "w+b",
+        delete: bool = False,
+    ) -> Path:
+        """
+        Create a named temporary file.
+
+        Args:
+            content: Optional content to write
+            suffix: File suffix
+            prefix: File prefix
+            dir: Directory for the file
+            mode: File mode
+            delete: Whether to delete on close
+
+        Returns:
+            Path to the created file
+        """
+        if isinstance(dir, Path):
+            dir = str(dir)
+
+        # Use Foundation's temp_file with cleanup=False since we manage cleanup
+        with foundation_temp_file(
+            suffix=suffix, prefix=prefix, dir=dir, text="b" not in mode, cleanup=False
+        ) as path:
+            if content is not None:
+                if isinstance(content, str):
+                    if "b" in mode:
+                        path.write_bytes(content.encode())
+                    else:
+                        path.write_text(content)
+                else:
+                    path.write_bytes(content)
+
+        if not delete:
+            created_files.append(path)
+
+        return path
+
+    yield _make_named_file
+
+    # Cleanup
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def temp_file_with_content():
+    """
+    Create temporary files with specific content.
+
+    Returns:
+        Function that creates files with content.
+    """
+    created_files = []
+
+    def _make_file(content: str | bytes, suffix: str = ".txt", encoding: str = "utf-8") -> Path:
+        """
+        Create a temporary file with content.
+
+        Args:
+            content: Content to write
+            suffix: File suffix
+            encoding: Text encoding (for str content)
+
+        Returns:
+            Path to created file
+        """
+        # Use Foundation's temp_file
+        with foundation_temp_file(suffix=suffix, text=not isinstance(content, bytes), cleanup=False) as path:
+            if isinstance(content, bytes):
+                path.write_bytes(content)
+            else:
+                path.write_text(content, encoding=encoding)
+
+        created_files.append(path)
+        return path
+
+    yield _make_file
+
+    # Cleanup
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def temp_binary_file():
+    """
+    Create temporary binary files.
+
+    Returns:
+        Function that creates binary files.
+    """
+    created_files = []
+
+    def _make_binary(size: int = 1024, pattern: bytes = None, suffix: str = ".bin") -> Path:
+        """
+        Create a temporary binary file.
+
+        Args:
+            size: File size in bytes
+            pattern: Optional byte pattern to repeat
+            suffix: File suffix
+
+        Returns:
+            Path to created binary file
+        """
+        if pattern is None:
+            # Create pseudo-random binary data
+            content = bytes(random.randint(0, 255) for _ in range(size))
+        else:
+            # Repeat pattern to reach size
+            repetitions = size // len(pattern) + 1
+            content = (pattern * repetitions)[:size]
+
+        with foundation_temp_file(suffix=suffix, text=False, cleanup=False) as path:
+            path.write_bytes(content)
+
+        created_files.append(path)
+        return path
+
+    yield _make_binary
+
+    # Cleanup
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def temp_csv_file():
+    """
+    Create temporary CSV files for testing.
+
+    Returns:
+        Function that creates CSV files.
+    """
+    created_files = []
+
+    def _make_csv(headers: list[str], rows: list[list], suffix: str = ".csv") -> Path:
+        """
+        Create a temporary CSV file.
+
+        Args:
+            headers: Column headers
+            rows: Data rows
+            suffix: File suffix
+
+        Returns:
+            Path to created CSV file
+        """
+        with foundation_temp_file(suffix=suffix, text=True, cleanup=False) as path:
+            with open(path, "w", newline="") as f:
+                writer = csv.writer(f)
+                writer.writerow(headers)
+                writer.writerows(rows)
+
+        created_files.append(path)
+        return path
+
+    yield _make_csv
+
+    # Cleanup
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def temp_json_file():
+    """
+    Create temporary JSON files for testing.
+
+    Returns:
+        Function that creates JSON files.
+    """
+    created_files = []
+
+    def _make_json(data: dict | list, suffix: str = ".json", indent: int = 2) -> Path:
+        """
+        Create a temporary JSON file.
+
+        Args:
+            data: JSON data to write
+            suffix: File suffix
+            indent: JSON indentation
+
+        Returns:
+            Path to created JSON file
+        """
+        with foundation_temp_file(suffix=suffix, text=True, cleanup=False) as path:
+            with open(path, "w") as f:
+                json.dump(data, f, indent=indent)
+
+        created_files.append(path)
+        return path
+
+    yield _make_json
+
+    # Cleanup
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+__all__ = [
+    "temp_binary_file",
+    "temp_csv_file",
+    "temp_file",
+    "temp_file_with_content",
+    "temp_json_file",
+    "temp_named_file",
+]

provide/testkit/file/directory_fixtures.py

@@ -0,0 +1,105 @@
+"""
+Directory-specific test fixtures.
+
+Fixtures for creating temporary directories, nested structures,
+and standard test directory layouts.
+"""
+
+from collections.abc import Generator
+from pathlib import Path
+
+import pytest
+
+from provide.foundation.file import temp_dir as foundation_temp_dir
+
+
+@pytest.fixture
+def temp_directory() -> Generator[Path, None, None]:
+    """
+    Create a temporary directory that's cleaned up after test.
+
+    Yields:
+        Path to the temporary directory.
+    """
+    with foundation_temp_dir() as temp_dir:
+        yield temp_dir
+
+
+@pytest.fixture
+def test_files_structure() -> Generator[tuple[Path, Path], None, None]:
+    """
+    Create standard test file structure with files and subdirectories.
+
+    Creates:
+        - source/
+            - file1.txt (contains "Content 1")
+            - file2.txt (contains "Content 2")
+            - subdir/
+                - file3.txt (contains "Content 3")
+
+    Yields:
+        Tuple of (temp_path, source_path)
+    """
+    with foundation_temp_dir() as path:
+        source = path / "source"
+        source.mkdir()
+
+        # Create test files
+        (source / "file1.txt").write_text("Content 1")
+        (source / "file2.txt").write_text("Content 2")
+
+        # Create subdirectory with files
+        subdir = source / "subdir"
+        subdir.mkdir()
+        (subdir / "file3.txt").write_text("Content 3")
+
+        yield path, source
+
+
+@pytest.fixture
+def nested_directory_structure() -> Generator[Path, None, None]:
+    """
+    Create a deeply nested directory structure for testing.
+
+    Creates:
+        - level1/
+            - level2/
+                - level3/
+                    - deep_file.txt
+            - file_l2.txt
+        - file_l1.txt
+
+    Yields:
+        Path to the root of the structure.
+    """
+    with foundation_temp_dir() as root:
+        # Create nested structure
+        deep_dir = root / "level1" / "level2" / "level3"
+        deep_dir.mkdir(parents=True)
+
+        # Add files at different levels
+        (root / "file_l1.txt").write_text("Level 1 file")
+        (root / "level1" / "file_l2.txt").write_text("Level 2 file")
+        (deep_dir / "deep_file.txt").write_text("Deep file")
+
+        yield root
+
+
+@pytest.fixture
+def empty_directory() -> Generator[Path, None, None]:
+    """
+    Create an empty temporary directory.
+
+    Yields:
+        Path to an empty directory.
+    """
+    with foundation_temp_dir() as temp_dir:
+        yield temp_dir
+
+
+__all__ = [
+    "empty_directory",
+    "nested_directory_structure",
+    "temp_directory",
+    "test_files_structure",
+]

provide/testkit/file/fixtures.py

@@ -0,0 +1,49 @@
+"""
+File and Directory Test Fixtures.
+
+Core file testing fixtures with re-exports from specialized modules.
+Common fixtures for testing file operations, creating temporary directories,
+and standard test file structures used across the provide-io ecosystem.
+"""
+
+# Re-export all fixtures from specialized modules
+from provide.testkit.file.content_fixtures import (
+    temp_binary_file,
+    temp_csv_file,
+    temp_file,
+    temp_file_with_content,
+    temp_json_file,
+    temp_named_file,
+)
+from provide.testkit.file.directory_fixtures import (
+    empty_directory,
+    nested_directory_structure,
+    temp_directory,
+    test_files_structure,
+)
+from provide.testkit.file.special_fixtures import (
+    binary_file,
+    readonly_file,
+    temp_executable_file,
+    temp_symlink,
+)
+
+__all__ = [
+    # Directory fixtures
+    "temp_directory",
+    "test_files_structure",
+    "nested_directory_structure",
+    "empty_directory",
+    # Special file fixtures
+    "binary_file",
+    "readonly_file",
+    "temp_symlink",
+    "temp_executable_file",
+    # Content-based fixtures
+    "temp_file",
+    "temp_named_file",
+    "temp_file_with_content",
+    "temp_binary_file",
+    "temp_csv_file",
+    "temp_json_file",
+]

provide/testkit/file/special_fixtures.py

@@ -0,0 +1,141 @@
+"""
+Special file test fixtures.
+
+Fixtures for creating specialized files like binary files, read-only files,
+symbolic links, and executable files.
+"""
+
+from collections.abc import Generator
+from pathlib import Path
+import stat
+
+import pytest
+
+from provide.foundation.file import temp_file as foundation_temp_file
+from provide.foundation.file.safe import safe_delete
+
+
+@pytest.fixture
+def binary_file() -> Generator[Path, None, None]:
+    """
+    Create a temporary binary file for testing.
+
+    Yields:
+        Path to a binary file containing sample binary data.
+    """
+    with foundation_temp_file(suffix=".bin", text=False, cleanup=False) as path:
+        # Write some binary data
+        path.write_bytes(
+            b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09" + b"\xff\xfe\xfd\xfc\xfb\xfa\xf9\xf8\xf7\xf6"
+        )
+
+    yield path
+    safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def readonly_file() -> Generator[Path, None, None]:
+    """
+    Create a read-only file for permission testing.
+
+    Yields:
+        Path to a read-only file.
+    """
+    with foundation_temp_file(suffix=".txt", text=True, cleanup=False) as path:
+        path.write_text("Read-only content")
+
+    # Make file read-only
+    path.chmod(0o444)
+
+    yield path
+
+    # Restore write permission for cleanup
+    path.chmod(0o644)
+    safe_delete(path, missing_ok=True)
+
+
+@pytest.fixture
+def temp_symlink():
+    """
+    Create temporary symbolic links for testing.
+
+    Returns:
+        Function that creates symbolic links.
+    """
+    created_links = []
+
+    def _make_symlink(target: Path | str, link_name: Path | str = None) -> Path:
+        """
+        Create a temporary symbolic link.
+
+        Args:
+            target: Target path for the symlink
+            link_name: Optional link name (auto-generated if None)
+
+        Returns:
+            Path to created symlink
+        """
+        target = Path(target)
+
+        if link_name is None:
+            with foundation_temp_file(cleanup=True) as temp_path:
+                link_name = Path(str(temp_path) + "_link")
+        else:
+            link_name = Path(link_name)
+
+        link_name.symlink_to(target)
+        created_links.append(link_name)
+
+        return link_name
+
+    yield _make_symlink
+
+    # Cleanup
+    for link in created_links:
+        safe_delete(link, missing_ok=True)
+
+
+@pytest.fixture
+def temp_executable_file():
+    """
+    Create temporary executable files for testing.
+
+    Returns:
+        Function that creates executable files.
+    """
+    created_files = []
+
+    def _make_executable(content: str = "#!/bin/sh\necho 'test'\n", suffix: str = ".sh") -> Path:
+        """
+        Create a temporary executable file.
+
+        Args:
+            content: Script content
+            suffix: File suffix
+
+        Returns:
+            Path to created executable file
+        """
+        with foundation_temp_file(suffix=suffix, text=True, cleanup=False) as path:
+            path.write_text(content)
+
+        # Make executable
+        current = path.stat().st_mode
+        path.chmod(current | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+        created_files.append(path)
+        return path
+
+    yield _make_executable
+
+    # Cleanup
+    for path in created_files:
+        safe_delete(path, missing_ok=True)
+
+
+__all__ = [
+    "binary_file",
+    "readonly_file",
+    "temp_executable_file",
+    "temp_symlink",
+]