fishertools 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

tests/test_patterns_docstrings.py

@@ -0,0 +1,473 @@
+"""
+Property-based tests for pattern docstrings in fishertools.patterns.
+
+Tests the correctness property that all pattern classes and functions have
+comprehensive docstrings explaining their purpose and usage.
+
+**Validates: Requirements 7.3, 12.1**
+"""
+
+import pytest
+import inspect
+from hypothesis import given, strategies as st
+
+from fishertools.patterns.menu import simple_menu
+from fishertools.patterns.storage import JSONStorage
+from fishertools.patterns.logger import SimpleLogger
+from fishertools.patterns.cli import SimpleCLI
+
+
+class TestAllPatternsHaveDocstrings:
+    """
+    Property 10: All Patterns Have Docstrings
+    
+    For all pattern classes and functions, they should have non-empty docstrings
+    explaining their purpose.
+    
+    **Validates: Requirements 7.3, 12.1**
+    """
+    
+    def test_simple_menu_has_docstring(self):
+        """Test that simple_menu() has a docstring."""
+        assert simple_menu.__doc__ is not None
+        assert len(simple_menu.__doc__) > 0
+        assert simple_menu.__doc__.strip() != ""
+    
+    def test_simple_menu_docstring_is_meaningful(self):
+        """Test that simple_menu() docstring is meaningful."""
+        docstring = simple_menu.__doc__
+        
+        # Should contain key information
+        assert "menu" in docstring.lower()
+        assert "options" in docstring.lower()
+        
+        # Should be substantial
+        assert len(docstring) >= 100
+    
+    def test_simple_menu_docstring_has_parameters(self):
+        """Test that simple_menu() docstring documents parameters."""
+        docstring = simple_menu.__doc__
+        
+        # Should mention parameters
+        assert "Parameters" in docstring or "parameters" in docstring.lower()
+        assert "options" in docstring.lower()
+    
+    def test_simple_menu_docstring_has_returns(self):
+        """Test that simple_menu() docstring documents return value."""
+        docstring = simple_menu.__doc__
+        
+        # Should mention return value
+        assert "Returns" in docstring or "returns" in docstring.lower()
+    
+    def test_simple_menu_docstring_has_example(self):
+        """Test that simple_menu() docstring includes an example."""
+        docstring = simple_menu.__doc__
+        
+        # Should include example
+        assert "Example" in docstring or "example" in docstring.lower()
+    
+    def test_jsonstorage_class_has_docstring(self):
+        """Test that JSONStorage class has a docstring."""
+        assert JSONStorage.__doc__ is not None
+        assert len(JSONStorage.__doc__) > 0
+        assert JSONStorage.__doc__.strip() != ""
+    
+    def test_jsonstorage_class_docstring_is_meaningful(self):
+        """Test that JSONStorage class docstring is meaningful."""
+        docstring = JSONStorage.__doc__
+        
+        # Should contain key information
+        assert "JSON" in docstring or "json" in docstring.lower()
+        assert "storage" in docstring.lower() or "save" in docstring.lower()
+        
+        # Should be substantial
+        assert len(docstring) >= 100
+    
+    def test_jsonstorage_init_has_docstring(self):
+        """Test that JSONStorage.__init__() has a docstring."""
+        assert JSONStorage.__init__.__doc__ is not None
+        assert len(JSONStorage.__init__.__doc__) > 0
+    
+    def test_jsonstorage_save_has_docstring(self):
+        """Test that JSONStorage.save() has a docstring."""
+        assert JSONStorage.save.__doc__ is not None
+        assert len(JSONStorage.save.__doc__) > 0
+        assert "save" in JSONStorage.save.__doc__.lower()
+    
+    def test_jsonstorage_load_has_docstring(self):
+        """Test that JSONStorage.load() has a docstring."""
+        assert JSONStorage.load.__doc__ is not None
+        assert len(JSONStorage.load.__doc__) > 0
+        assert "load" in JSONStorage.load.__doc__.lower()
+    
+    def test_jsonstorage_exists_has_docstring(self):
+        """Test that JSONStorage.exists() has a docstring."""
+        assert JSONStorage.exists.__doc__ is not None
+        assert len(JSONStorage.exists.__doc__) > 0
+        assert "exist" in JSONStorage.exists.__doc__.lower()
+    
+    def test_jsonstorage_class_docstring_has_parameters(self):
+        """Test that JSONStorage class docstring documents parameters."""
+        docstring = JSONStorage.__doc__
+        
+        # Should mention parameters
+        assert "Parameters" in docstring or "parameters" in docstring.lower()
+        assert "file_path" in docstring.lower()
+    
+    def test_jsonstorage_class_docstring_has_methods(self):
+        """Test that JSONStorage class docstring documents methods."""
+        docstring = JSONStorage.__doc__
+        
+        # Should mention methods
+        assert "Methods" in docstring or "methods" in docstring.lower()
+        assert "save" in docstring.lower()
+        assert "load" in docstring.lower()
+    
+    def test_jsonstorage_class_docstring_has_example(self):
+        """Test that JSONStorage class docstring includes an example."""
+        docstring = JSONStorage.__doc__
+        
+        # Should include example
+        assert "Example" in docstring or "example" in docstring.lower()
+    
+    def test_simplelogger_class_has_docstring(self):
+        """Test that SimpleLogger class has a docstring."""
+        assert SimpleLogger.__doc__ is not None
+        assert len(SimpleLogger.__doc__) > 0
+        assert SimpleLogger.__doc__.strip() != ""
+    
+    def test_simplelogger_class_docstring_is_meaningful(self):
+        """Test that SimpleLogger class docstring is meaningful."""
+        docstring = SimpleLogger.__doc__
+        
+        # Should contain key information
+        assert "log" in docstring.lower()
+        assert "file" in docstring.lower() or "message" in docstring.lower()
+        
+        # Should be substantial
+        assert len(docstring) >= 100
+    
+    def test_simplelogger_init_has_docstring(self):
+        """Test that SimpleLogger.__init__() has a docstring."""
+        assert SimpleLogger.__init__.__doc__ is not None
+        assert len(SimpleLogger.__init__.__doc__) > 0
+    
+    def test_simplelogger_info_has_docstring(self):
+        """Test that SimpleLogger.info() has a docstring."""
+        assert SimpleLogger.info.__doc__ is not None
+        assert len(SimpleLogger.info.__doc__) > 0
+        assert "info" in SimpleLogger.info.__doc__.lower()
+    
+    def test_simplelogger_warning_has_docstring(self):
+        """Test that SimpleLogger.warning() has a docstring."""
+        assert SimpleLogger.warning.__doc__ is not None
+        assert len(SimpleLogger.warning.__doc__) > 0
+        assert "warning" in SimpleLogger.warning.__doc__.lower()
+    
+    def test_simplelogger_error_has_docstring(self):
+        """Test that SimpleLogger.error() has a docstring."""
+        assert SimpleLogger.error.__doc__ is not None
+        assert len(SimpleLogger.error.__doc__) > 0
+        assert "error" in SimpleLogger.error.__doc__.lower()
+    
+    def test_simplelogger_class_docstring_has_parameters(self):
+        """Test that SimpleLogger class docstring documents parameters."""
+        docstring = SimpleLogger.__doc__
+        
+        # Should mention parameters
+        assert "Parameters" in docstring or "parameters" in docstring.lower()
+        assert "file_path" in docstring.lower()
+    
+    def test_simplelogger_class_docstring_has_methods(self):
+        """Test that SimpleLogger class docstring documents methods."""
+        docstring = SimpleLogger.__doc__
+        
+        # Should mention methods
+        assert "Methods" in docstring or "methods" in docstring.lower()
+        assert "info" in docstring.lower()
+        assert "warning" in docstring.lower()
+        assert "error" in docstring.lower()
+    
+    def test_simplelogger_class_docstring_has_example(self):
+        """Test that SimpleLogger class docstring includes an example."""
+        docstring = SimpleLogger.__doc__
+        
+        # Should include example
+        assert "Example" in docstring or "example" in docstring.lower()
+    
+    def test_simplecli_class_has_docstring(self):
+        """Test that SimpleCLI class has a docstring."""
+        assert SimpleCLI.__doc__ is not None
+        assert len(SimpleCLI.__doc__) > 0
+        assert SimpleCLI.__doc__.strip() != ""
+    
+    def test_simplecli_class_docstring_is_meaningful(self):
+        """Test that SimpleCLI class docstring is meaningful."""
+        docstring = SimpleCLI.__doc__
+        
+        # Should contain key information
+        assert "CLI" in docstring or "command" in docstring.lower()
+        assert "interface" in docstring.lower() or "command" in docstring.lower()
+        
+        # Should be substantial
+        assert len(docstring) >= 100
+    
+    def test_simplecli_init_has_docstring(self):
+        """Test that SimpleCLI.__init__() has a docstring."""
+        assert SimpleCLI.__init__.__doc__ is not None
+        assert len(SimpleCLI.__init__.__doc__) > 0
+    
+    def test_simplecli_command_has_docstring(self):
+        """Test that SimpleCLI.command() has a docstring."""
+        assert SimpleCLI.command.__doc__ is not None
+        assert len(SimpleCLI.command.__doc__) > 0
+        assert "command" in SimpleCLI.command.__doc__.lower()
+    
+    def test_simplecli_run_has_docstring(self):
+        """Test that SimpleCLI.run() has a docstring."""
+        assert SimpleCLI.run.__doc__ is not None
+        assert len(SimpleCLI.run.__doc__) > 0
+        assert "run" in SimpleCLI.run.__doc__.lower() or "execute" in SimpleCLI.run.__doc__.lower()
+    
+    def test_simplecli_class_docstring_has_parameters(self):
+        """Test that SimpleCLI class docstring documents parameters."""
+        docstring = SimpleCLI.__doc__
+        
+        # Should mention parameters
+        assert "Parameters" in docstring or "parameters" in docstring.lower()
+        assert "name" in docstring.lower()
+        assert "description" in docstring.lower()
+    
+    def test_simplecli_class_docstring_has_methods(self):
+        """Test that SimpleCLI class docstring documents methods."""
+        docstring = SimpleCLI.__doc__
+        
+        # Should mention methods
+        assert "Methods" in docstring or "methods" in docstring.lower()
+        assert "command" in docstring.lower()
+        assert "run" in docstring.lower()
+    
+    def test_simplecli_class_docstring_has_example(self):
+        """Test that SimpleCLI class docstring includes an example."""
+        docstring = SimpleCLI.__doc__
+        
+        # Should include example
+        assert "Example" in docstring or "example" in docstring.lower()
+    
+    def test_all_pattern_classes_have_docstrings(self):
+        """Test that all pattern classes have docstrings."""
+        pattern_classes = [JSONStorage, SimpleLogger, SimpleCLI]
+        
+        for cls in pattern_classes:
+            assert cls.__doc__ is not None, f"{cls.__name__} missing docstring"
+            assert len(cls.__doc__) > 0, f"{cls.__name__} has empty docstring"
+            assert cls.__doc__.strip() != "", f"{cls.__name__} has whitespace-only docstring"
+    
+    def test_all_pattern_functions_have_docstrings(self):
+        """Test that all pattern functions have docstrings."""
+        pattern_functions = [simple_menu]
+        
+        for func in pattern_functions:
+            assert func.__doc__ is not None, f"{func.__name__} missing docstring"
+            assert len(func.__doc__) > 0, f"{func.__name__} has empty docstring"
+            assert func.__doc__.strip() != "", f"{func.__name__} has whitespace-only docstring"
+    
+    def test_all_pattern_public_methods_have_docstrings(self):
+        """Test that all public methods in pattern classes have docstrings."""
+        pattern_classes = [JSONStorage, SimpleLogger, SimpleCLI]
+        
+        for cls in pattern_classes:
+            # Get all public methods
+            for name, method in inspect.getmembers(cls, predicate=inspect.isfunction):
+                if not name.startswith('_'):
+                    assert method.__doc__ is not None, f"{cls.__name__}.{name} missing docstring"
+                    assert len(method.__doc__) > 0, f"{cls.__name__}.{name} has empty docstring"
+    
+    def test_docstrings_contain_meaningful_content(self):
+        """Test that docstrings contain meaningful content."""
+        pattern_items = [
+            (simple_menu, "simple_menu"),
+            (JSONStorage, "JSONStorage"),
+            (SimpleLogger, "SimpleLogger"),
+            (SimpleCLI, "SimpleCLI")
+        ]
+        
+        for item, name in pattern_items:
+            docstring = item.__doc__
+            
+            # Should have substantial content
+            assert len(docstring) >= 50, f"{name} docstring too short"
+            
+            # Should contain alphabetic characters
+            assert any(c.isalpha() for c in docstring), f"{name} docstring has no text"
+    
+    def test_docstrings_follow_format(self):
+        """Test that docstrings follow a consistent format."""
+        pattern_classes = [JSONStorage, SimpleLogger, SimpleCLI]
+        
+        for cls in pattern_classes:
+            docstring = cls.__doc__
+            
+            # Should have a summary line
+            lines = docstring.strip().split('\n')
+            assert len(lines) > 1, f"{cls.__name__} docstring too short"
+            
+            # First line should be a summary
+            summary = lines[0].strip()
+            assert len(summary) > 10, f"{cls.__name__} summary too short"
+    
+    def test_method_docstrings_document_parameters(self):
+        """Test that method docstrings document their parameters."""
+        # Check JSONStorage.save
+        save_doc = JSONStorage.save.__doc__
+        assert "Parameters" in save_doc or "parameters" in save_doc.lower()
+        assert "data" in save_doc.lower()
+        
+        # Check SimpleLogger.info
+        info_doc = SimpleLogger.info.__doc__
+        assert "Parameters" in info_doc or "parameters" in info_doc.lower()
+        assert "message" in info_doc.lower()
+        
+        # Check SimpleCLI.command
+        command_doc = SimpleCLI.command.__doc__
+        assert "Parameters" in command_doc or "parameters" in command_doc.lower()
+    
+    def test_method_docstrings_document_returns(self):
+        """Test that method docstrings document return values."""
+        # Check JSONStorage.load
+        load_doc = JSONStorage.load.__doc__
+        assert "Returns" in load_doc or "returns" in load_doc.lower()
+        
+        # Check JSONStorage.exists
+        exists_doc = JSONStorage.exists.__doc__
+        assert "Returns" in exists_doc or "returns" in exists_doc.lower()
+    
+    def test_docstrings_are_not_just_pass_statements(self):
+        """Test that docstrings are actual documentation, not just pass."""
+        pattern_items = [
+            simple_menu,
+            JSONStorage,
+            SimpleLogger,
+            SimpleCLI
+        ]
+        
+        for item in pattern_items:
+            docstring = item.__doc__
+            
+            # Should not be just "pass" or similar
+            assert docstring.lower().strip() != "pass"
+            assert docstring.lower().strip() != "todo"
+            assert docstring.lower().strip() != "..."
+    
+    def test_docstrings_have_examples(self):
+        """Test that main docstrings include usage examples."""
+        pattern_items = [
+            (simple_menu, "simple_menu"),
+            (JSONStorage, "JSONStorage"),
+            (SimpleLogger, "SimpleLogger"),
+            (SimpleCLI, "SimpleCLI")
+        ]
+        
+        for item, name in pattern_items:
+            docstring = item.__doc__
+            
+            # Should include example
+            assert "Example" in docstring or "example" in docstring.lower(), \
+                f"{name} docstring missing example"
+    
+    def test_docstrings_have_notes_or_warnings(self):
+        """Test that docstrings include helpful notes."""
+        pattern_items = [
+            (simple_menu, "simple_menu"),
+            (JSONStorage, "JSONStorage"),
+            (SimpleLogger, "SimpleLogger"),
+            (SimpleCLI, "SimpleCLI")
+        ]
+        
+        for item, name in pattern_items:
+            docstring = item.__doc__
+            
+            # Should include note or important information
+            has_note = "Note" in docstring or "note" in docstring.lower()
+            has_important = "Important" in docstring or "important" in docstring.lower()
+            
+            assert has_note or has_important, \
+                f"{name} docstring missing notes or important information"
+
+
+class TestDocstringQuality:
+    """Test the quality and completeness of docstrings."""
+    
+    def test_simple_menu_docstring_mentions_exit(self):
+        """Test that simple_menu docstring mentions exit behavior."""
+        docstring = simple_menu.__doc__
+        
+        assert "quit" in docstring.lower() or "exit" in docstring.lower()
+    
+    def test_jsonstorage_docstring_mentions_directory_creation(self):
+        """Test that JSONStorage docstring mentions directory creation."""
+        docstring = JSONStorage.__doc__
+        
+        assert "director" in docstring.lower() or "create" in docstring.lower()
+    
+    def test_simplelogger_docstring_mentions_timestamp(self):
+        """Test that SimpleLogger docstring mentions timestamp format."""
+        docstring = SimpleLogger.__doc__
+        
+        assert "timestamp" in docstring.lower() or "time" in docstring.lower()
+    
+    def test_simplecli_docstring_mentions_decorator(self):
+        """Test that SimpleCLI docstring mentions decorator usage."""
+        docstring = SimpleCLI.__doc__
+        
+        assert "decorator" in docstring.lower() or "@" in docstring
+    
+    def test_all_docstrings_are_accessible(self):
+        """Test that all docstrings are accessible via help()."""
+        pattern_items = [simple_menu, JSONStorage, SimpleLogger, SimpleCLI]
+        
+        for item in pattern_items:
+            # Should be able to get help
+            help_text = inspect.getdoc(item)
+            assert help_text is not None
+            assert len(help_text) > 0
+
+
+class TestDocstringConsistency:
+    """Test consistency across docstrings."""
+    
+    def test_all_class_docstrings_have_similar_structure(self):
+        """Test that all class docstrings follow a similar structure."""
+        pattern_classes = [JSONStorage, SimpleLogger, SimpleCLI]
+        
+        for cls in pattern_classes:
+            docstring = cls.__doc__
+            
+            # Should have Parameters section
+            assert "Parameters" in docstring or "parameters" in docstring.lower()
+            
+            # Should have Methods section (for classes)
+            assert "Methods" in docstring or "methods" in docstring.lower()
+            
+            # Should have Example section
+            assert "Example" in docstring or "example" in docstring.lower()
+    
+    def test_all_method_docstrings_have_parameters_section(self):
+        """Test that all methods with parameters document them."""
+        # JSONStorage.save has parameters
+        save_doc = JSONStorage.save.__doc__
+        assert "Parameters" in save_doc or "parameters" in save_doc.lower()
+        
+        # SimpleLogger.info has parameters
+        info_doc = SimpleLogger.info.__doc__
+        assert "Parameters" in info_doc or "parameters" in info_doc.lower()
+    
+    def test_all_method_docstrings_have_returns_section(self):
+        """Test that all methods document their return values."""
+        # JSONStorage.load returns data
+        load_doc = JSONStorage.load.__doc__
+        assert "Returns" in load_doc or "returns" in load_doc.lower()
+        
+        # JSONStorage.exists returns bool
+        exists_doc = JSONStorage.exists.__doc__
+        assert "Returns" in exists_doc or "returns" in exists_doc.lower()