Merge pull request #119 from Dog-Face-Development/copilot/add-github-actions-tests

Add comprehensive test suite with GitHub Actions integration

Author: willtheorangeguy

.github/workflows/pytest.yml

@@ -13,10 +13,14 @@ jobs:
       uses: actions/setup-python@v6
       with:
         python-version: '3.x'
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y python3-tk
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
     - name: Run tests
-      run: pytest
+      run: pytest -v
 

docs/TESTING.md

@@ -0,0 +1,127 @@
+# Testing Documentation
+
+This document describes the test suite for Mom's Canning Timer and how tests are integrated with GitHub Actions.
+
+## Test Structure
+
+The test suite is organized into three main test files:
+
+### tests/test_main.py
+Tests for the main timer functionality in `main.py`.
+
+**Test Cases:**
+- `test_timeStart1_callable()` - Verifies timeStart1 function is callable
+- `test_timeStart1_execution()` - Tests timeStart1 runs without errors (with mocking)
+- `test_timeStart2_callable()` - Verifies timeStart2 function is callable
+- `test_timeStart2_execution()` - Tests timeStart2 runs without errors (with mocking)
+- `test_timeStart3_callable()` - Verifies timeStart3 function is callable
+- `test_timeStart3_execution()` - Tests timeStart3 runs without errors (with mocking)
+- `test_timeStart4_callable()` - Verifies timeStart4 function is callable
+- `test_timeStart4_execution()` - Tests timeStart4 runs without errors (with mocking)
+- `test_timer_callable()` - Verifies timer function is callable
+- `test_timer_creates_window()` - Tests timer creates a Tk window properly
+
+**Testing Approach:**
+- Uses `unittest.mock.patch` to mock `time.sleep()` and `print()` functions
+- Uses threading to prevent tests from blocking for 15 minutes
+- Verifies functions execute and call expected methods without full timer execution
+
+### tests/test_init.py
+Tests for the package initialization in `__init__.py`.
+
+**Test Cases:**
+- `test_all_attribute_exists()` - Verifies `__all__` attribute exists
+- `test_all_contains_main()` - Verifies `__all__` contains 'main'
+- `test_all_is_list()` - Verifies `__all__` is a list
+
+### tests/test_entrypoint.py
+Tests for the entry point module in `__main__.py`.
+
+**Test Cases:**
+- `test_main_module_exists()` - Verifies `__main__.py` file exists
+- `test_main_has_correct_imports()` - Verifies correct import structure
+- `test_main_has_docstring()` - Verifies proper documentation
+
+## Running Tests
+
+### Locally
+
+1. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+2. Install tkinter (if not already installed):
+```bash
+# On Ubuntu/Debian
+sudo apt-get install python3-tk
+
+# On macOS (using Homebrew)
+brew install python-tk
+
+# On Windows
+# tkinter is usually included with Python installation
+```
+
+3. Run tests:
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_main.py
+
+# Run specific test
+pytest tests/test_main.py::TestTimer::test_timeStart1_callable
+```
+
+### In GitHub Actions
+
+Tests run automatically on:
+- Every push to any branch
+- Every pull request
+
+The GitHub Actions workflow:
+1. Sets up Python environment
+2. Installs system dependencies (python3-tk)
+3. Installs Python dependencies from requirements.txt
+4. Runs pytest with verbose output
+
+See `.github/workflows/pytest.yml` for the complete workflow configuration.
+
+## Test Dependencies
+
+- **pytest** - Testing framework
+- **unittest.mock** - Built-in Python mocking library
+- **threading** - Built-in Python threading library for non-blocking tests
+- **python3-tk** - System dependency for tkinter GUI framework
+
+## Coverage
+
+Current test coverage includes:
+- All timer start functions (timeStart1-4)
+- Main timer GUI function
+- Package initialization
+- Entry point module structure
+
+## Best Practices
+
+1. **Mocking Long-Running Operations**: Timer functions are designed to run for 15 minutes. Tests use mocking to verify logic without waiting.
+
+2. **Threading for GUI Tests**: GUI operations can block test execution. Tests use threading with timeouts to prevent hanging.
+
+3. **Testing Without Display**: Tests are designed to run in headless environments (like GitHub Actions) by mocking Tk window creation.
+
+4. **Minimal Changes**: Tests verify behavior without modifying the original code, maintaining backward compatibility.
+
+## Future Improvements
+
+Potential areas for test expansion:
+- Integration tests for complete timer workflows
+- Performance tests for timer accuracy
+- UI interaction tests with GUI automation tools
+- Edge case testing (system sleep, interruptions, etc.)
+- Code coverage reporting

tests/test_entrypoint.py

@@ -0,0 +1,44 @@
+"""Tests for __main__.py."""
+
+# pylint: disable=invalid-name
+
+import sys
+import os
+import unittest
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+class TestEntrypoint(unittest.TestCase):
+    """Tests for __main__.py."""
+
+    def test_main_module_exists(self):
+        """Test that __main__.py file exists."""
+        main_path = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "__main__.py"
+        )
+        self.assertTrue(os.path.exists(main_path))
+
+    def test_main_has_correct_imports(self):
+        """Test that __main__.py has the correct structure."""
+        main_path = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "__main__.py"
+        )
+        with open(main_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            self.assertIn("from main import timer", content)
+            self.assertIn('if __name__ == "__main__":', content)
+
+    def test_main_has_docstring(self):
+        """Test that __main__.py has a docstring."""
+        main_path = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "__main__.py"
+        )
+        with open(main_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            # Check for docstring at the beginning
+            self.assertIn('"""', content)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_init.py

@@ -0,0 +1,29 @@
+"""Tests for __init__.py."""
+
+import sys
+import os
+import unittest
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import __init__
+
+
+class TestInit(unittest.TestCase):
+    """Tests for __init__.py."""
+
+    def test_all_attribute_exists(self):
+        """Test that __all__ attribute exists."""
+        self.assertTrue(hasattr(__init__, "__all__"))
+
+    def test_all_contains_main(self):
+        """Test that __all__ contains 'main'."""
+        self.assertIn("main", __init__.__all__)
+
+    def test_all_is_list(self):
+        """Test that __all__ is a list."""
+        self.assertIsInstance(__init__.__all__, list)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_main.py

@@ -1,34 +1,110 @@
 """Tests for main.py."""
+
 # pylint: disable=invalid-name, wrong-import-position
 
 import sys
 import os
 import unittest
+from unittest.mock import patch, MagicMock
+import threading
 
 sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-from main import timeStart1, timeStart2, timeStart3, timeStart4
+from main import timeStart1, timeStart2, timeStart3, timeStart4, timer
 
 
 class TestTimer(unittest.TestCase):
     """Tests for timer.py."""
 
-    def test_timeStart1(self):
-        """Test timeStart1 function."""
+    def _run_function_in_thread(self, func, timeout=2.0):
+        """Helper method to run a function in a thread with timeout."""
+        thread = threading.Thread(target=func)
+        thread.daemon = True
+        thread.start()
+        thread.join(timeout=timeout)
+
+    def test_timeStart1_callable(self):
+        """Test timeStart1 function is callable."""
         self.assertTrue(callable(timeStart1))
 
-    def test_timeStart2(self):
-        """Test timeStart2 function."""
+    def test_timeStart2_callable(self):
+        """Test timeStart2 function is callable."""
         self.assertTrue(callable(timeStart2))
 
-    def test_timeStart3(self):
-        """Test timeStart3 function."""
+    def test_timeStart3_callable(self):
+        """Test timeStart3 function is callable."""
         self.assertTrue(callable(timeStart3))
 
-    def test_timeStart4(self):
-        """Test timeStart4 function."""
+    def test_timeStart4_callable(self):
+        """Test timeStart4 function is callable."""
         self.assertTrue(callable(timeStart4))
 
+    @patch("time.sleep")
+    @patch("builtins.print")
+    def test_timeStart1_execution(self, mock_print, mock_sleep):
+        """Test timeStart1 runs without errors when mocked."""
+        self._run_function_in_thread(timeStart1)
+
+        # Verify that print was called (timer is running)
+        self.assertTrue(mock_print.called)
+        # Verify that sleep was called (timer is working)
+        self.assertTrue(mock_sleep.called)
+
+    @patch("time.sleep")
+    @patch("builtins.print")
+    def test_timeStart2_execution(self, mock_print, mock_sleep):
+        """Test timeStart2 runs without errors when mocked."""
+        self._run_function_in_thread(timeStart2)
+
+        self.assertTrue(mock_print.called)
+        self.assertTrue(mock_sleep.called)
+
+    @patch("time.sleep")
+    @patch("builtins.print")
+    def test_timeStart3_execution(self, mock_print, mock_sleep):
+        """Test timeStart3 runs without errors when mocked."""
+        self._run_function_in_thread(timeStart3)
+
+        self.assertTrue(mock_print.called)
+        self.assertTrue(mock_sleep.called)
+
+    @patch("time.sleep")
+    @patch("builtins.print")
+    def test_timeStart4_execution(self, mock_print, mock_sleep):
+        """Test timeStart4 runs without errors when mocked."""
+        self._run_function_in_thread(timeStart4)
+
+        self.assertTrue(mock_print.called)
+        self.assertTrue(mock_sleep.called)
 
+    def test_timer_callable(self):
+        """Test timer function is callable."""
+        self.assertTrue(callable(timer))
+
+    @patch("main.Tk")
+    def test_timer_creates_window(self, mock_tk):
+        """Test timer function creates a Tk window."""
+        # Mock the Tk instance and its methods
+        mock_window = MagicMock()
+        mock_tk.return_value = mock_window
+
+        # Run timer in a thread to avoid blocking
+        def run_timer():
+            try:
+                timer()
+            except Exception:
+                # Expected to fail when mainloop is not properly mocked
+                pass
+
+        self._run_function_in_thread(run_timer, timeout=1.0)
+
+        # Verify Tk was instantiated
+        mock_tk.assert_called_once()
+        # Verify window title was set
+        mock_window.title.assert_called_once_with("Canning Timer")
+
+
+if __name__ == "__main__":
+    unittest.main()
 if __name__ == "__main__":
     unittest.main()