cli-test-framework 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

cli_test_framework/__init__.py

@@ -0,0 +1,21 @@
+"""
+CLI Test Framework - A powerful command-line testing framework
+
+This package provides tools for testing command-line applications and scripts
+with support for parallel execution and advanced file comparison capabilities.
+"""
+
+__version__ = "0.2.2"
+__author__ = "Xiaotong Wang"
+__email__ = "xiaotongwang98@gmail.com"
+
+# Import main classes for convenient access
+from .runners.json_runner import JSONRunner
+from .runners.parallel_json_runner import ParallelJSONRunner
+from .runners.yaml_runner import YAMLRunner
+
+__all__ = [
+    'JSONRunner',
+    'ParallelJSONRunner', 
+    'YAMLRunner',
+] 

cli_test_framework/cli.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+CLI Test Framework - Command Line Interface
+
+This module provides the main command-line interface for the CLI Testing Framework.
+"""
+
+import argparse
+import sys
+import os
+from pathlib import Path
+
+from .runners import JSONRunner, ParallelJSONRunner, YAMLRunner
+
+
+def create_parser():
+    """Create and configure the argument parser"""
+    parser = argparse.ArgumentParser(
+        description="CLI Testing Framework - A powerful tool for testing command-line applications",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  cli-test run test_cases.json
+  cli-test run test_cases.json --parallel --workers 4
+  cli-test run test_cases.yaml --workspace /path/to/project
+        """
+    )
+    
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+    
+    # Run command
+    run_parser = subparsers.add_parser('run', help='Run test cases from a configuration file')
+    run_parser.add_argument('config_file', help='Path to the test configuration file (JSON or YAML)')
+    run_parser.add_argument('--workspace', '-w', help='Working directory for test execution')
+    run_parser.add_argument('--parallel', '-p', action='store_true', help='Run tests in parallel')
+    run_parser.add_argument('--workers', type=int, help='Number of parallel workers (default: CPU count)')
+    run_parser.add_argument('--execution-mode', choices=['thread', 'process'], default='thread',
+                           help='Parallel execution mode (default: thread)')
+    run_parser.add_argument('--output-format', choices=['text', 'json', 'html'], default='text',
+                           help='Output format for test results')
+    run_parser.add_argument('--verbose', '-v', action='store_true', help='Enable verbose output')
+    run_parser.add_argument('--debug', action='store_true', help='Enable debug mode')
+    
+    return parser
+
+
+def run_tests(args):
+    """Run tests based on command line arguments"""
+    config_file = Path(args.config_file)
+    
+    if not config_file.exists():
+        print(f"Error: Configuration file not found: {config_file}")
+        return False
+    
+    # Determine file type
+    file_ext = config_file.suffix.lower()
+    
+    try:
+        if args.parallel:
+            # Use parallel runner
+            runner = ParallelJSONRunner(
+                config_file=str(config_file),
+                workspace=args.workspace,
+                max_workers=args.workers,
+                execution_mode=args.execution_mode
+            )
+        else:
+            # Use appropriate single-threaded runner
+            if file_ext in ['.json']:
+                runner = JSONRunner(
+                    config_file=str(config_file),
+                    workspace=args.workspace
+                )
+            elif file_ext in ['.yaml', '.yml']:
+                runner = YAMLRunner(
+                    config_file=str(config_file),
+                    workspace=args.workspace
+                )
+            else:
+                print(f"Error: Unsupported configuration file format: {file_ext}")
+                return False
+        
+        # Run tests
+        print(f"Running tests from: {config_file}")
+        if args.parallel:
+            print(f"Parallel mode: {args.execution_mode}, workers: {args.workers or 'auto'}")
+        
+        success = runner.run_tests()
+        
+        # Output results
+        if hasattr(runner, 'results'):
+            results = runner.results
+            print(f"\nTest Results:")
+            print(f"Total tests: {results.get('total_tests', 0)}")
+            print(f"Passed: {results.get('passed', 0)}")
+            print(f"Failed: {results.get('failed', 0)}")
+            
+            if args.verbose and 'details' in results:
+                print("\nDetailed Results:")
+                for result in results['details']:
+                    status_symbol = "✓" if result['status'] == 'passed' else "✗"
+                    print(f"  {status_symbol} {result['name']}: {result['status']}")
+                    if result['status'] == 'failed' and result.get('message'):
+                        print(f"    Error: {result['message']}")
+        
+        return success
+        
+    except Exception as e:
+        print(f"Error running tests: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return False
+
+
+def main():
+    """Main entry point for the CLI"""
+    parser = create_parser()
+    args = parser.parse_args()
+    
+    if args.command == 'run':
+        success = run_tests(args)
+        sys.exit(0 if success else 1)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main() 

cli_test_framework/core/__init__.py

@@ -0,0 +1,15 @@
+"""
+Core components for the CLI Testing Framework
+"""
+
+from .base_runner import BaseRunner
+from .parallel_runner import ParallelRunner
+from .test_case import TestCase
+from .assertions import Assertions
+
+__all__ = [
+    'BaseRunner',
+    'ParallelRunner', 
+    'TestCase',
+    'Assertions'
+]

{core → cli_test_framework/core}/assertions.py

@@ -1,32 +1,32 @@
-import re
-from typing import Any, Pattern
-
-class Assertions:
-    @staticmethod
-    def equals(actual: Any, expected: Any, message: str = "") -> bool:
-        if actual != expected:
-            raise AssertionError(f"{message} Expected: {expected}, but got: {actual}")
-        return True
-
-    @staticmethod
-    def contains(container: str, item: str, message: str = "") -> bool:
-        """
-        Check if the item is contained within the container string.
-        This method returns True if the item is found anywhere within the container,
-        even if the container contains other information.
-        """
-        if item not in container:
-            raise AssertionError(f"{message} Expected to contain: {item}")
-        return True
-
-    @staticmethod
-    def matches(text: str, pattern: str, message: str = "") -> bool:
-        if not re.search(pattern, text):
-            raise AssertionError(f"{message} Text does not match pattern: {pattern}")
-        return True
-
-    @staticmethod
-    def return_code_equals(actual: int, expected: int, message: str = "") -> bool:
-        if actual != expected:
-            raise AssertionError(f"{message} Expected return code: {expected}, got: {actual}")
+import re
+from typing import Any, Pattern
+
+class Assertions:
+    @staticmethod
+    def equals(actual: Any, expected: Any, message: str = "") -> bool:
+        if actual != expected:
+            raise AssertionError(f"{message} Expected: {expected}, but got: {actual}")
+        return True
+
+    @staticmethod
+    def contains(container: str, item: str, message: str = "") -> bool:
+        """
+        Check if the item is contained within the container string.
+        This method returns True if the item is found anywhere within the container,
+        even if the container contains other information.
+        """
+        if item not in container:
+            raise AssertionError(f"{message} Expected to contain: {item}")
+        return True
+
+    @staticmethod
+    def matches(text: str, pattern: str, message: str = "") -> bool:
+        if not re.search(pattern, text):
+            raise AssertionError(f"{message} Text does not match pattern: {pattern}")
+        return True
+
+    @staticmethod
+    def return_code_equals(actual: int, expected: int, message: str = "") -> bool:
+        if actual != expected:
+            raise AssertionError(f"{message} Expected return code: {expected}, got: {actual}")
         return True

cli_test_framework/file_comparator/__init__.py

@@ -0,0 +1,9 @@
+"""
+File comparison module for cli-test-framework.
+This module provides functionality for comparing different types of files.
+"""
+
+from .factory import ComparatorFactory
+from .result import ComparisonResult
+
+__all__ = ['ComparatorFactory', 'ComparisonResult'] 

cli_test_framework/file_comparator/base_comparator.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+@file base_comparator.py
+@brief Base abstract class for file comparison operations
+@author Xiaotong Wang
+@date 2025
+"""
+
+from abc import ABC, abstractmethod
+import logging
+from pathlib import Path
+from .result import ComparisonResult, Difference
+
+class BaseComparator(ABC):
+    """
+    @brief Base abstract class for all file comparators
+    @details This class defines the interface and common functionality for all file comparators.
+             It provides basic file comparison operations and logging capabilities.
+    """
+    
+    def __init__(self, encoding="utf-8", chunk_size=8192, verbose=False):
+        """
+        @brief Initialize the base comparator
+        @param encoding str: File encoding to use (default: "utf-8")
+        @param chunk_size int: Size of chunks for reading large files (default: 8192)
+        @param verbose bool: Enable verbose logging (default: False)
+        """
+        self.encoding = encoding
+        self.chunk_size = chunk_size
+        self.logger = logging.getLogger(f"file_comparator.{self.__class__.__name__}")
+        if verbose:
+            self.logger.setLevel(logging.DEBUG)
+    
+    @abstractmethod
+    def read_content(self, file_path, start_line=0, end_line=None, start_column=0, end_column=None):
+        """
+        @brief Read file content with specified range
+        @param file_path Path: Path to the file to read
+        @param start_line int: Starting line number (0-based)
+        @param end_line int: Ending line number (0-based, None for end of file)
+        @param start_column int: Starting column number (0-based)
+        @param end_column int: Ending column number (0-based, None for end of line)
+        @return object: File content in a format suitable for comparison
+        """
+        pass
+
+    @abstractmethod
+    def compare_content(self, content1, content2):
+        """
+        @brief Compare two content objects and return comparison details
+        @param content1 object: First content object to compare
+        @param content2 object: Second content object to compare
+        @return tuple: (bool, list) - (identical, differences)
+        """
+        pass
+
+    def compare_files(self, file1, file2, start_line=0, end_line=None, start_column=0, end_column=None):
+        """
+        @brief Compare two files with the specified parameters
+        @param file1 Path: Path to the first file
+        @param file2 Path: Path to the second file
+        @param start_line int: Starting line number (0-based)
+        @param end_line int: Ending line number (0-based, None for end of file)
+        @param start_column int: Starting column number (0-based)
+        @param end_column int: Ending column number (0-based, None for end of line)
+        @return ComparisonResult: Result object containing comparison details
+        """
+        result = ComparisonResult(
+            file1=str(file1),
+            file2=str(file2),
+            start_line=start_line,
+            end_line=end_line,
+            start_column=start_column,
+            end_column=end_column
+        )
+        
+        try:
+            self.logger.info(f"Comparing files: {file1} and {file2}")
+            
+            # Record file metadata
+            file1_path = Path(file1)
+            file2_path = Path(file2)
+            result.file1_size = file1_path.stat().st_size
+            result.file2_size = file2_path.stat().st_size
+            
+            # Read content with specified ranges
+            self.logger.debug(f"Reading content from files")
+            content1 = self.read_content(file1, start_line, end_line, start_column, end_column)
+            content2 = self.read_content(file2, start_line, end_line, start_column, end_column)
+            
+            # Compare content
+            self.logger.debug(f"Comparing content")
+            identical, differences = self.compare_content(content1, content2)
+            
+            # Update result
+            result.identical = identical
+            result.differences = differences
+            
+            return result
+            
+        except Exception as e:
+            self.logger.error(f"Error during comparison: {str(e)}")
+            result.error = str(e)
+            result.identical = False
+            return result

cli_test_framework/file_comparator/binary_comparator.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+@file binary_comparator.py
+@brief Binary file comparator implementation with efficient byte-level comparison
+@author Xiaotong Wang
+@date 2025
+"""
+
+import hashlib
+from .base_comparator import BaseComparator
+from .result import Difference
+from concurrent.futures import ThreadPoolExecutor
+
+class BinaryComparator(BaseComparator):
+    """
+    @brief Comparator for binary files with efficient byte-level comparison
+    @details This class implements binary file comparison with support for:
+             - Byte-level difference detection
+             - Similarity index calculation using LCS
+             - Parallel processing for large files
+             - File hash calculation
+    """
+    
+    def __init__(self, encoding="utf-8", chunk_size=8192, verbose=False, similarity=False, num_threads=4):
+        """
+        @brief Initialize the binary comparator
+        @param encoding str: File encoding (not used for binary files)
+        @param chunk_size int: Size of chunks for reading large files
+        @param verbose bool: Enable verbose logging
+        @param similarity bool: Enable similarity index calculation
+        @param num_threads int: Number of threads for parallel processing
+        """
+        super().__init__(encoding, chunk_size, verbose)
+        self.similarity = similarity
+        self.num_threads = num_threads
+
+    def read_content(self, file_path, start_line=0, end_line=None, start_column=0, end_column=None):
+        """
+        @brief Read binary content with specified range
+        @param file_path Path: Path to the binary file to read
+        @param start_line int: Starting byte offset (interpreted as bytes for binary files)
+        @param end_line int: Ending byte offset (interpreted as bytes for binary files)
+        @param start_column int: Ignored for binary files
+        @param end_column int: Ignored for binary files
+        @return bytes: Binary content within the specified range
+        @throws ValueError: If byte offsets are invalid
+        @throws FileNotFoundError: If file doesn't exist
+        @throws IOError: If there are other file reading errors
+        """
+        try:
+            self.logger.debug(f"Reading binary file: {file_path}")
+            
+            # For binary files, interpret start_line as byte offset
+            start_offset = start_line
+            end_offset = end_line
+            
+            with open(file_path, 'rb') as f:
+                if start_offset > 0:
+                    f.seek(start_offset)
+                
+                if end_offset is not None:
+                    if end_offset <= start_offset:
+                        raise ValueError("End offset must be greater than start offset")
+                    bytes_to_read = end_offset - start_offset
+                    content = f.read(bytes_to_read)
+                else:
+                    content = f.read()
+                    
+            return content
+                
+        except FileNotFoundError:
+            raise ValueError(f"File not found: {file_path}")
+        except IOError as e:
+            raise ValueError(f"Error reading file {file_path}: {str(e)}")
+    
+    def compare_content(self, content1, content2):
+        """
+        @brief Compare binary content efficiently
+        @param content1 bytes: First binary content to compare
+        @param content2 bytes: Second binary content to compare
+        @return tuple: (bool, list) - (identical, differences)
+        @details Performs efficient byte-level comparison of binary content.
+                 Reports differences with hex context and limits the number
+                 of differences to avoid overwhelming output.
+        """
+        self.logger.debug(f"Comparing binary content")
+        
+        if len(content1) != len(content2):
+            differences = [Difference(
+                position="file size",
+                expected=f"{len(content1)} bytes",
+                actual=f"{len(content2)} bytes",
+                diff_type="size"
+            )]
+            identical = False
+        elif content1 == content2:
+            differences = []
+            identical = True
+        else:
+            identical = False
+            differences = []
+            offset = 0
+            max_differences = 10  # Limit number of differences reported
+        
+            for i in range(0, len(content1), self.chunk_size):
+                chunk1 = content1[i:i+self.chunk_size]
+                chunk2 = content2[i:i+self.chunk_size]
+                
+                if chunk1 != chunk2:
+                    # Find the exact byte position where the difference starts
+                    for j in range(len(chunk1)):
+                        if j >= len(chunk2) or chunk1[j] != chunk2[j]:
+                            diff_pos = i + j
+                            # Show a few bytes before and after the difference for context
+                            context_size = 8
+                            start_ctx = max(0, diff_pos - context_size)
+                            end_ctx = min(len(content1), diff_pos + context_size)
+                            
+                            # Create hex representations of the differing sections
+                            expected_bytes = content1[start_ctx:end_ctx]
+                            actual_bytes = content2[start_ctx:min(len(content2), end_ctx)]
+                            
+                            expected_hex = ' '.join(f"{b:02x}" for b in expected_bytes)
+                            actual_hex = ' '.join(f"{b:02x}" for b in actual_bytes)
+                            
+                            differences.append(Difference(
+                                position=f"byte {diff_pos}",
+                                expected=expected_hex,
+                                actual=actual_hex,
+                                diff_type="content"
+                            ))
+                            break
+                            
+                    if len(differences) >= max_differences:
+                        differences.append(Difference(
+                            position=None,
+                            expected=None,
+                            actual=None,
+                            diff_type=f"more differences not shown"
+                        ))
+                        break
+        
+        return identical, differences
+
+    def compute_lcs_length(self, a: bytes, b: bytes) -> int:
+        """
+        @brief Compute the length of the longest common subsequence
+        @param a bytes: First binary sequence
+        @param b bytes: Second binary sequence
+        @return int: Length of the longest common subsequence
+        @details Uses dynamic programming with memory optimization to compute LCS.
+                 Supports parallel processing for large sequences.
+        """
+        if not a or not b:
+            return 0
+
+        def lcs_worker(start, end):
+            previous = [0] * (len(b) + 1)
+            for i in range(start, end):
+                current = [0] * (len(b) + 1)
+                for j in range(1, len(b) + 1):
+                    if a[i - 1] == b[j - 1]:
+                        current[j] = previous[j - 1] + 1
+                    else:
+                        current[j] = max(previous[j], current[j - 1])
+                previous = current
+            return previous[len(b)]
+
+        chunk_size = len(a) // self.num_threads
+        futures = []
+
+        with ThreadPoolExecutor(max_workers=self.num_threads) as executor:
+            for i in range(self.num_threads):
+                start = i * chunk_size
+                end = (i + 1) * chunk_size if i != self.num_threads - 1 else len(a)
+                futures.append(executor.submit(lcs_worker, start, end))
+
+        lcs_length = sum(f.result() for f in futures)
+        return lcs_length
+
+    def compare_files(self, file1, file2, start_line=0, end_line=None, start_column=0, end_column=None):
+        """
+        @brief Compare two binary files with optional similarity calculation
+        @param file1 Path: Path to the first binary file
+        @param file2 Path: Path to the second binary file
+        @param start_line int: Starting byte offset
+        @param end_line int: Ending byte offset
+        @param start_column int: Ignored for binary files
+        @param end_column int: Ignored for binary files
+        @return ComparisonResult: Result object containing comparison details
+        """
+        from pathlib import Path
+        from .result import ComparisonResult
+        result = ComparisonResult(
+            file1=str(file1),
+            file2=str(file2),
+            start_line=start_line,
+            end_line=end_line,
+            start_column=start_column,
+            end_column=end_column
+        )
+        try:
+            self.logger.info(f"Comparing files: {file1} and {file2}")
+            file1_path = Path(file1)
+            file2_path = Path(file2)
+            result.file1_size = file1_path.stat().st_size
+            result.file2_size = file2_path.stat().st_size
+            self.logger.debug("Reading content from files")
+            content1 = self.read_content(file1, start_line, end_line, start_column, end_column)
+            content2 = self.read_content(file2, start_line, end_line, start_column, end_column)
+            self.logger.debug("Comparing content")
+            identical, differences = self.compare_content(content1, content2)
+            result.identical = identical
+            result.differences = differences
+            if self.similarity:
+                if (len(content1) + len(content2)) > 0:
+                    lcs_len = self.compute_lcs_length(content1, content2)
+                    similarity = 2 * lcs_len / (len(content1) + len(content2))
+                else:
+                    similarity = 1
+                result.similarity = similarity
+            return result
+        except Exception as e:
+            self.logger.error(f"Error during comparison: {str(e)}")
+            result.error = str(e)
+            result.identical = False
+            return result
+
+    def get_file_hash(self, file_path, chunk_size=8192):
+        """
+        @brief Calculate SHA-256 hash of a file efficiently
+        @param file_path Path: Path to the file to hash
+        @param chunk_size int: Size of chunks for reading large files
+        @return str: Hexadecimal representation of the file's SHA-256 hash
+        """
+        h = hashlib.sha256()
+        with open(file_path, 'rb') as f:
+            for chunk in iter(lambda: f.read(chunk_size), b''):
+                h.update(chunk)
+        return h.hexdigest()