Documentation/TESTING.md

@@ -0,0 +1,259 @@
+# Running Tests
+
+This document describes how to run the test suite for the vgui-cicd project.
+
+## Test Structure
+
+The project includes comprehensive unit tests for the diagram caching functionality:
+
+```
+abschnitte/
+├── tests.py                              # Tests for rendering functions
+├── management/
+│   └── commands/
+│       └── test_clear_diagram_cache.py  # Tests for management command
+
+diagramm_proxy/
+└── test_diagram_cache.py                # Tests for caching module
+```
+
+## Running All Tests
+
+To run the entire test suite:
+
+```bash
+python manage.py test
+```
+
+## Running Specific Test Modules
+
+Run tests for a specific app:
+
+```bash
+# Test abschnitte rendering
+python manage.py test abschnitte
+
+# Test diagram caching
+python manage.py test diagramm_proxy
+
+# Test management commands
+python manage.py test abschnitte.management.commands
+```
+
+## Running Individual Test Cases
+
+Run a specific test case:
+
+```bash
+# Test diagram cache functionality
+python manage.py test diagramm_proxy.test_diagram_cache.DiagramCacheTestCase
+
+# Test rendering functions
+python manage.py test abschnitte.tests.RenderTextabschnitteTestCase
+
+# Test management command
+python manage.py test abschnitte.management.commands.test_clear_diagram_cache
+```
+
+## Running Individual Tests
+
+Run a single test method:
+
+```bash
+python manage.py test abschnitte.tests.RenderTextabschnitteTestCase.test_render_diagram_success
+```
+
+## Test Coverage
+
+To generate a coverage report, install coverage.py:
+
+```bash
+pip install coverage
+```
+
+Then run:
+
+```bash
+# Run tests with coverage
+coverage run --source='.' manage.py test
+
+# Generate coverage report
+coverage report
+
+# Generate HTML coverage report
+coverage html
+# Open htmlcov/index.html in browser
+```
+
+## Test Options
+
+### Verbose Output
+
+Get more detailed output:
+
+```bash
+python manage.py test --verbosity=2
+```
+
+### Keep Test Database
+
+Keep the test database after tests complete (useful for debugging):
+
+```bash
+python manage.py test --keepdb
+```
+
+### Fail Fast
+
+Stop after first test failure:
+
+```bash
+python manage.py test --failfast
+```
+
+### Parallel Testing
+
+Run tests in parallel (faster for large test suites):
+
+```bash
+python manage.py test --parallel
+```
+
+## What the Tests Cover
+
+### Diagram Caching Tests (`diagramm_proxy/test_diagram_cache.py`)
+
+- ✅ Hash computation and consistency
+- ✅ Cache path generation
+- ✅ Cache miss (diagram generation)
+- ✅ Cache hit (using cached diagrams)
+- ✅ HTTP error handling
+- ✅ Cache clearing (all and by type)
+- ✅ Unicode content handling
+- ✅ Timeout configuration
+- ✅ Full lifecycle integration tests
+
+### Rendering Tests (`abschnitte/tests.py`)
+
+- ✅ Text rendering with markdown
+- ✅ Unordered and ordered lists
+- ✅ Table rendering
+- ✅ Diagram rendering (success and error)
+- ✅ Diagram with custom options
+- ✅ Code blocks
+- ✅ Edge cases (empty content, missing types)
+- ✅ Multiple sections
+- ✅ Mixed content integration tests
+
+### Management Command Tests (`abschnitte/management/commands/test_clear_diagram_cache.py`)
+
+- ✅ Clearing all cache
+- ✅ Clearing by specific type
+- ✅ Clearing empty cache
+- ✅ Command help text
+- ✅ Full workflow integration
+
+## Continuous Integration
+
+These tests are designed to run in CI/CD pipelines. Example GitHub Actions workflow:
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+      - name: Run tests
+        run: |
+          python manage.py test --verbosity=2
+```
+
+## Debugging Failed Tests
+
+If tests fail, you can:
+
+1. **Run with verbose output** to see detailed error messages:
+   ```bash
+   python manage.py test --verbosity=2
+   ```
+
+2. **Run specific failing test** to isolate the issue:
+   ```bash
+   python manage.py test path.to.TestCase.test_method
+   ```
+
+3. **Use pdb for debugging**:
+   ```python
+   import pdb; pdb.set_trace()  # Add to test code
+   ```
+
+4. **Check test database**:
+   ```bash
+   python manage.py test --keepdb
+   ```
+
+## Test Requirements
+
+The tests use:
+- Django's built-in `TestCase` class
+- Python's `unittest.mock` for mocking external dependencies
+- `@override_settings` for temporary setting changes
+- `tempfile` for creating temporary directories
+
+No additional testing libraries are required beyond what's in `requirements.txt`.
+
+## Writing New Tests
+
+When adding new features, follow these patterns:
+
+1. **Test file location**: Place tests in the same app as the code being tested
+2. **Test class naming**: Use descriptive names ending in `TestCase`
+3. **Test method naming**: Start with `test_` and describe what's being tested
+4. **Use mocks**: Mock external dependencies (HTTP calls, file systems when needed)
+5. **Clean up**: Use `setUp()` and `tearDown()` or temporary directories
+6. **Test edge cases**: Include tests for error conditions and edge cases
+
+Example:
+
+```python
+from django.test import TestCase
+from unittest.mock import patch
+
+class MyFeatureTestCase(TestCase):
+    def setUp(self):
+        """Set up test fixtures."""
+        self.test_data = "example"
+    
+    def test_basic_functionality(self):
+        """Test that the feature works correctly."""
+        result = my_function(self.test_data)
+        self.assertEqual(result, expected_value)
+    
+    @patch('my_app.module.external_call')
+    def test_with_mock(self, mock_call):
+        """Test with mocked external dependency."""
+        mock_call.return_value = "mocked"
+        result = my_function(self.test_data)
+        mock_call.assert_called_once()
+```
+
+## Test Best Practices
+
+- Write tests before or alongside code (TDD approach)
+- Each test should test one thing
+- Tests should be independent (no shared state)
+- Use descriptive test names
+- Mock external dependencies (HTTP, filesystem, etc.)
+- Test both success and failure cases
+- Aim for high code coverage (>80%)