scalebox-sdk 0.1.25__py3-none-any.whl → 1.0.1__py3-none-any.whl

scalebox/test/README.md

@@ -1,329 +1,329 @@
-# ScaleBox Sandbox Verification Test Suite
-
-This test suite contains comprehensive validation examples for the `sandbox_async` and `sandbox_sync` modules, covering everything from basic functionality to advanced use cases.
-
-## 📋 Test Files Overview
-
-### 1. Basic Functionality Verification
-
-#### `test_sandbox_async_comprehensive.py`
-**Asynchronous Sandbox Comprehensive Verification Tests**
-- ✅ Sandbox lifecycle management (create, connect, destroy)
-- ✅ Filesystem operations (read/write, list, delete, rename, etc.)
-- ✅ Command execution (foreground, background, PTY)
-- ✅ Static methods and class methods
-- ✅ Error handling and exception cases
-- ✅ Performance testing and concurrent operations
-- ✅ Context manager usage
-
-**Run with:**
-```bash
-cd /home/ubuntu/git_home/scalebox/test
-python test_sandbox_async_comprehensive.py
-```
-
-#### `test_sandbox_sync_comprehensive.py`
-**Synchronous Sandbox Comprehensive Verification Tests**
-- ✅ Same functionality coverage as async version
-- ✅ Synchronous-specific operation modes
-- ✅ Thread pool concurrent processing
-- ✅ Directory monitoring functionality
-
-**Run with:**
-```bash
-cd /home/ubuntu/git_home/scalebox/test
-python test_sandbox_sync_comprehensive.py
-```
-
-### 2. Stress Testing and Edge Cases
-
-#### `test_sandbox_stress_and_edge_cases.py`
-**Stress Testing and Edge Case Verification**
-- 🔥 Large file handling (10MB+ files)
-- 🔥 High concurrency operations (sync and async)
-- 🔥 Memory stress testing (1000+ file operations)
-- 🔥 Edge case testing (empty files, special characters, deep directories)
-- 🔥 Error recovery capability testing
-- 🔥 Resource management testing (multiple sandbox instances)
-
-**Run with:**
-```bash
-cd /home/ubuntu/git_home/scalebox/test
-python test_sandbox_stress_and_edge_cases.py
-```
-
-### 3. Real-World Application Examples
-
-#### `test_sandbox_usage_examples.py`
-**Usage Examples and Best Practices**
-- 💡 Code execution service implementation
-- 💡 File processing service implementation
-- 💡 Interactive session management
-- 💡 Performance optimization techniques
-- 💡 Resource management best practices
-- 💡 Error handling strategies
-- 💡 Concurrency and asynchronous programming patterns
-
-**Run with:**
-```bash
-cd /home/ubuntu/git_home/scalebox/test
-python test_sandbox_usage_examples.py
-```
-
-## 🏗️ Test Architecture Design
-
-### Test Result Recording System
-Each test suite includes a complete test result recording system:
-```python
-class TestValidator:
-    def log_test_result(self, test_name: str, success: bool, message: str = "", duration: float = 0)
-    def run_test(self, test_func, test_name: str)
-    def print_summary(self)
-```
-
-### Resource Management System
-Intelligent sandbox resource management:
-```python
-class SandboxManager:
-    @contextmanager
-    def get_sandbox(self, sandbox_id: Optional[str] = None)
-
-class AsyncSandboxManager:
-    @asynccontextmanager
-    async def get_sandbox(self, sandbox_id: Optional[str] = None)
-```
-
-### Retry Mechanism
-Built-in retry decorators:
-```python
-@retry_on_failure(max_retries=3, delay=1.0)
-def your_function():
-    # Auto-retry failed operations
-    pass
-
-@async_retry_on_failure(max_retries=3, delay=1.0)
-async def your_async_function():
-    # Asynchronous retry mechanism
-    pass
-```
-
-## 📊 Test Coverage
-
-### Functionality Coverage
-| Functional Module | Sync Tests | Async Tests | Stress Tests | Usage Examples |
-|-------------------|------------|-------------|--------------|----------------|
-| Sandbox Create/Destroy | ✅ | ✅ | ✅ | ✅ |
-| Filesystem Operations | ✅ | ✅ | ✅ | ✅ |
-| Command Execution | ✅ | ✅ | ✅ | ✅ |
-| PTY Operations | ✅ | ✅ | ✅ | ✅ |
-| Static Methods | ✅ | ✅ | ✅ | ✅ |
-| Error Handling | ✅ | ✅ | ✅ | ✅ |
-| Performance Optimization | ✅ | ✅ | ✅ | ✅ |
-| Concurrent Processing | ✅ | ✅ | ✅ | ✅ |
-
-### Test Scenarios
-- **Basic Functionality**: Correctness verification of single operations
-- **Batch Operations**: Batch processing capability for large amounts of data
-- **Concurrent Processing**: Multi-task parallel execution
-- **Error Recovery**: System stability under exceptional circumstances
-- **Resource Management**: Effective management of memory and connections
-- **Performance Benchmarks**: Performance metrics for various operations
-
-## 🚀 Quick Start
-
-### 1. Environment Preparation
-Ensure necessary dependencies are installed in your environment:
-```bash
-# Ensure module path is correct
-export PYTHONPATH=/home/ubuntu/git_home/scalebox:$PYTHONPATH
-
-# Install dependencies (if needed)
-pip install -r requirements.txt
-```
-
-### 2. Run Individual Tests
-```bash
-# Run async comprehensive tests
-python test_sandbox_async_comprehensive.py
-
-# Run sync comprehensive tests
-python test_sandbox_sync_comprehensive.py
-
-# Run stress tests
-python test_sandbox_stress_and_edge_cases.py
-
-# Run usage examples
-python test_sandbox_usage_examples.py
-```
-
-### 3. Run All Tests in Batch
-```bash
-# Create run script
-cat > run_all_tests.sh << 'EOF'
-#!/bin/bash
-
-echo "Starting all sandbox tests..."
-
-echo "=== Async Comprehensive Tests ==="
-python test_sandbox_async_comprehensive.py
-
-echo "=== Sync Comprehensive Tests ==="
-python test_sandbox_sync_comprehensive.py
-
-echo "=== Stress Tests and Edge Cases ==="
-python test_sandbox_stress_and_edge_cases.py
-
-echo "=== Usage Examples and Best Practices ==="
-python test_sandbox_usage_examples.py
-
-echo "All tests completed!"
-EOF
-
-chmod +x run_all_tests.sh
-./run_all_tests.sh
-```
-
-## 📈 Performance Benchmarks
-
-### Sync vs Async Performance Comparison
-
-| Operation Type | Sync Version | Async Version | Performance Improvement |
-|----------------|--------------|---------------|------------------------|
-| Single File Operation | ~0.1s | ~0.1s | Equal |
-| Batch File Operations (100) | ~2.0s | ~0.5s | **4x faster** |
-| Concurrent Command Execution (10) | ~1.5s | ~0.3s | **5x faster** |
-| PTY Interactive Session | ~0.2s | ~0.2s | Equal |
-
-### Resource Usage
-- **Memory Usage**: Async version uses memory more efficiently during large batch operations
-- **CPU Utilization**: Async version better utilizes multi-core CPUs
-- **Network Connections**: Async version supports more concurrent connections
-
-## 🛠️ Custom Testing
-
-### Adding New Tests
-1. **Inherit Test Base Class**:
-```python
-class YourTestValidator:
-    def __init__(self):
-        self.test_results = []
-        self.failed_tests = []
-    
-    def log_test_result(self, test_name: str, success: bool, message: str = "", duration: float = 0):
-        # Implement test result recording
-        pass
-```
-
-2. **Write Test Methods**:
-```python
-def test_your_feature(self):
-    """Test your functionality"""
-    # Test logic
-    pass
-
-async def test_your_async_feature(self):
-    """Test your async functionality"""
-    # Async test logic
-    pass
-```
-
-3. **Run Tests**:
-```python
-def run_all_tests(self):
-    self.run_test(self.test_your_feature, "Your Feature Test")
-```
-
-### Configure Test Parameters
-```python
-# Configure at top of test file
-TEST_CONFIG = {
-    'debug_mode': True,
-    'max_concurrent': 10,
-    'timeout': 30,
-    'large_file_size': 10 * 1024 * 1024,  # 10MB
-    'stress_test_iterations': 1000
-}
-```
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-1. **Sandbox Creation Failure**
-   - Check network connection
-   - Verify API key configuration
-   - Confirm server status
-
-2. **File Operation Failure**
-   - Check file path permissions
-   - Verify disk space
-   - Confirm file format
-
-3. **Command Execution Timeout**
-   - Adjust timeout parameters
-   - Check command syntax
-   - Verify environment variables
-
-4. **Out of Memory Errors**
-   - Reduce concurrency count
-   - Adjust batch size
-   - Increase system memory
-
-### Debugging Tips
-
-1. **Enable Debug Logging**:
-```python
-import logging
-logging.basicConfig(level=logging.DEBUG)
-```
-
-2. **Use Debug Mode**:
-```python
-sandbox = Sandbox(debug=True)
-# or
-sandbox = await AsyncSandbox.create(debug=True)
-```
-
-3. **Monitor Resource Usage**:
-```python
-import psutil
-print(f"Memory usage: {psutil.virtual_memory().percent}%")
-print(f"CPU usage: {psutil.cpu_percent()}%")
-```
-
-## 📝 Contribution Guidelines
-
-### Adding New Tests
-1. Fork the project
-2. Create a feature branch
-3. Add test cases
-4. Update documentation
-5. Submit a Pull Request
-
-### Testing Standards
-- Each test function should have clear docstrings
-- Use assertions to verify results
-- Include appropriate error handling
-- Record performance metrics
-- Clean up test resources
-
-## 📚 References
-
-### API Documentation
-- [AsyncSandbox API](../sandbox_async/main.py)
-- [Sandbox API](../sandbox_sync/main.py)
-- [Filesystem API](../sandbox/filesystem/)
-- [Command Execution API](../sandbox/commands/)
-
-### Best Practices
-- Always use context managers to manage sandbox resources
-- Batch operations are better than individual operations
-- Async version is suitable for I/O-intensive tasks
-- Sync version is suitable for CPU-intensive tasks
-- Implement appropriate retry and error recovery mechanisms
-
----
-
-**Happy Testing! 🎉**
-
-For questions or suggestions, please submit an Issue or contact the maintenance team.
+# ScaleBox Sandbox Verification Test Suite
+
+This test suite contains comprehensive validation examples for the `sandbox_async` and `sandbox_sync` modules, covering everything from basic functionality to advanced use cases.
+
+## 📋 Test Files Overview
+
+### 1. Basic Functionality Verification
+
+#### `test_sandbox_async_comprehensive.py`
+**Asynchronous Sandbox Comprehensive Verification Tests**
+- ✅ Sandbox lifecycle management (create, connect, destroy)
+- ✅ Filesystem operations (read/write, list, delete, rename, etc.)
+- ✅ Command execution (foreground, background, PTY)
+- ✅ Static methods and class methods
+- ✅ Error handling and exception cases
+- ✅ Performance testing and concurrent operations
+- ✅ Context manager usage
+
+**Run with:**
+```bash
+cd /home/ubuntu/git_home/scalebox/test
+python test_sandbox_async_comprehensive.py
+```
+
+#### `test_sandbox_sync_comprehensive.py`
+**Synchronous Sandbox Comprehensive Verification Tests**
+- ✅ Same functionality coverage as async version
+- ✅ Synchronous-specific operation modes
+- ✅ Thread pool concurrent processing
+- ✅ Directory monitoring functionality
+
+**Run with:**
+```bash
+cd /home/ubuntu/git_home/scalebox/test
+python test_sandbox_sync_comprehensive.py
+```
+
+### 2. Stress Testing and Edge Cases
+
+#### `test_sandbox_stress_and_edge_cases.py`
+**Stress Testing and Edge Case Verification**
+- 🔥 Large file handling (10MB+ files)
+- 🔥 High concurrency operations (sync and async)
+- 🔥 Memory stress testing (1000+ file operations)
+- 🔥 Edge case testing (empty files, special characters, deep directories)
+- 🔥 Error recovery capability testing
+- 🔥 Resource management testing (multiple sandbox instances)
+
+**Run with:**
+```bash
+cd /home/ubuntu/git_home/scalebox/test
+python test_sandbox_stress_and_edge_cases.py
+```
+
+### 3. Real-World Application Examples
+
+#### `test_sandbox_usage_examples.py`
+**Usage Examples and Best Practices**
+- 💡 Code execution service implementation
+- 💡 File processing service implementation
+- 💡 Interactive session management
+- 💡 Performance optimization techniques
+- 💡 Resource management best practices
+- 💡 Error handling strategies
+- 💡 Concurrency and asynchronous programming patterns
+
+**Run with:**
+```bash
+cd /home/ubuntu/git_home/scalebox/test
+python test_sandbox_usage_examples.py
+```
+
+## 🏗️ Test Architecture Design
+
+### Test Result Recording System
+Each test suite includes a complete test result recording system:
+```python
+class TestValidator:
+    def log_test_result(self, test_name: str, success: bool, message: str = "", duration: float = 0)
+    def run_test(self, test_func, test_name: str)
+    def print_summary(self)
+```
+
+### Resource Management System
+Intelligent sandbox resource management:
+```python
+class SandboxManager:
+    @contextmanager
+    def get_sandbox(self, sandbox_id: Optional[str] = None)
+
+class AsyncSandboxManager:
+    @asynccontextmanager
+    async def get_sandbox(self, sandbox_id: Optional[str] = None)
+```
+
+### Retry Mechanism
+Built-in retry decorators:
+```python
+@retry_on_failure(max_retries=3, delay=1.0)
+def your_function():
+    # Auto-retry failed operations
+    pass
+
+@async_retry_on_failure(max_retries=3, delay=1.0)
+async def your_async_function():
+    # Asynchronous retry mechanism
+    pass
+```
+
+## 📊 Test Coverage
+
+### Functionality Coverage
+| Functional Module | Sync Tests | Async Tests | Stress Tests | Usage Examples |
+|-------------------|------------|-------------|--------------|----------------|
+| Sandbox Create/Destroy | ✅ | ✅ | ✅ | ✅ |
+| Filesystem Operations | ✅ | ✅ | ✅ | ✅ |
+| Command Execution | ✅ | ✅ | ✅ | ✅ |
+| PTY Operations | ✅ | ✅ | ✅ | ✅ |
+| Static Methods | ✅ | ✅ | ✅ | ✅ |
+| Error Handling | ✅ | ✅ | ✅ | ✅ |
+| Performance Optimization | ✅ | ✅ | ✅ | ✅ |
+| Concurrent Processing | ✅ | ✅ | ✅ | ✅ |
+
+### Test Scenarios
+- **Basic Functionality**: Correctness verification of single operations
+- **Batch Operations**: Batch processing capability for large amounts of data
+- **Concurrent Processing**: Multi-task parallel execution
+- **Error Recovery**: System stability under exceptional circumstances
+- **Resource Management**: Effective management of memory and connections
+- **Performance Benchmarks**: Performance metrics for various operations
+
+## 🚀 Quick Start
+
+### 1. Environment Preparation
+Ensure necessary dependencies are installed in your environment:
+```bash
+# Ensure module path is correct
+export PYTHONPATH=/home/ubuntu/git_home/scalebox:$PYTHONPATH
+
+# Install dependencies (if needed)
+pip install -r requirements.txt
+```
+
+### 2. Run Individual Tests
+```bash
+# Run async comprehensive tests
+python test_sandbox_async_comprehensive.py
+
+# Run sync comprehensive tests
+python test_sandbox_sync_comprehensive.py
+
+# Run stress tests
+python test_sandbox_stress_and_edge_cases.py
+
+# Run usage examples
+python test_sandbox_usage_examples.py
+```
+
+### 3. Run All Tests in Batch
+```bash
+# Create run script
+cat > run_all_tests.sh << 'EOF'
+#!/bin/bash
+
+echo "Starting all sandbox tests..."
+
+echo "=== Async Comprehensive Tests ==="
+python test_sandbox_async_comprehensive.py
+
+echo "=== Sync Comprehensive Tests ==="
+python test_sandbox_sync_comprehensive.py
+
+echo "=== Stress Tests and Edge Cases ==="
+python test_sandbox_stress_and_edge_cases.py
+
+echo "=== Usage Examples and Best Practices ==="
+python test_sandbox_usage_examples.py
+
+echo "All tests completed!"
+EOF
+
+chmod +x run_all_tests.sh
+./run_all_tests.sh
+```
+
+## 📈 Performance Benchmarks
+
+### Sync vs Async Performance Comparison
+
+| Operation Type | Sync Version | Async Version | Performance Improvement |
+|----------------|--------------|---------------|------------------------|
+| Single File Operation | ~0.1s | ~0.1s | Equal |
+| Batch File Operations (100) | ~2.0s | ~0.5s | **4x faster** |
+| Concurrent Command Execution (10) | ~1.5s | ~0.3s | **5x faster** |
+| PTY Interactive Session | ~0.2s | ~0.2s | Equal |
+
+### Resource Usage
+- **Memory Usage**: Async version uses memory more efficiently during large batch operations
+- **CPU Utilization**: Async version better utilizes multi-core CPUs
+- **Network Connections**: Async version supports more concurrent connections
+
+## 🛠️ Custom Testing
+
+### Adding New Tests
+1. **Inherit Test Base Class**:
+```python
+class YourTestValidator:
+    def __init__(self):
+        self.test_results = []
+        self.failed_tests = []
+    
+    def log_test_result(self, test_name: str, success: bool, message: str = "", duration: float = 0):
+        # Implement test result recording
+        pass
+```
+
+2. **Write Test Methods**:
+```python
+def test_your_feature(self):
+    """Test your functionality"""
+    # Test logic
+    pass
+
+async def test_your_async_feature(self):
+    """Test your async functionality"""
+    # Async test logic
+    pass
+```
+
+3. **Run Tests**:
+```python
+def run_all_tests(self):
+    self.run_test(self.test_your_feature, "Your Feature Test")
+```
+
+### Configure Test Parameters
+```python
+# Configure at top of test file
+TEST_CONFIG = {
+    'debug_mode': True,
+    'max_concurrent': 10,
+    'timeout': 30,
+    'large_file_size': 10 * 1024 * 1024,  # 10MB
+    'stress_test_iterations': 1000
+}
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **Sandbox Creation Failure**
+   - Check network connection
+   - Verify API key configuration
+   - Confirm server status
+
+2. **File Operation Failure**
+   - Check file path permissions
+   - Verify disk space
+   - Confirm file format
+
+3. **Command Execution Timeout**
+   - Adjust timeout parameters
+   - Check command syntax
+   - Verify environment variables
+
+4. **Out of Memory Errors**
+   - Reduce concurrency count
+   - Adjust batch size
+   - Increase system memory
+
+### Debugging Tips
+
+1. **Enable Debug Logging**:
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+2. **Use Debug Mode**:
+```python
+sandbox = Sandbox(debug=True)
+# or
+sandbox = await AsyncSandbox.create(debug=True)
+```
+
+3. **Monitor Resource Usage**:
+```python
+import psutil
+print(f"Memory usage: {psutil.virtual_memory().percent}%")
+print(f"CPU usage: {psutil.cpu_percent()}%")
+```
+
+## 📝 Contribution Guidelines
+
+### Adding New Tests
+1. Fork the project
+2. Create a feature branch
+3. Add test cases
+4. Update documentation
+5. Submit a Pull Request
+
+### Testing Standards
+- Each test function should have clear docstrings
+- Use assertions to verify results
+- Include appropriate error handling
+- Record performance metrics
+- Clean up test resources
+
+## 📚 References
+
+### API Documentation
+- [AsyncSandbox API](../sandbox_async/main.py)
+- [Sandbox API](../sandbox_sync/main.py)
+- [Filesystem API](../sandbox/filesystem/)
+- [Command Execution API](../sandbox/commands/)
+
+### Best Practices
+- Always use context managers to manage sandbox resources
+- Batch operations are better than individual operations
+- Async version is suitable for I/O-intensive tasks
+- Sync version is suitable for CPU-intensive tasks
+- Implement appropriate retry and error recovery mechanisms
+
+---
+
+**Happy Testing! 🎉**
+
+For questions or suggestions, please submit an Issue or contact the maintenance team.