vgui-cicd/Documentation/TESTING.md

# 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%)