application-form-7/prompts/002-comprehensive-pytest-testing.md

<objective>
Create a comprehensive pytest test suite for the Flask job application system to ensure all functionality works correctly, including routes, validation, file uploads, YAML storage, and session management.

This test suite will validate that the application behaves correctly across all workflows and edge cases, providing confidence for future development and deployment.
</objective>

<context>
The Flask job application system consists of:
- 5-page workflow (email capture → personal info → motivation → uploads → confirmation)
- Email-based resume functionality with unique session IDs
- File-based storage using YAML for data and file system for attachments
- Comprehensive validation (email, phone, ZIP, birth year, file uploads)
- German language interface

Tech stack: Flask 3.0.0, PyYAML, Flask-Mail, pytest for testing

Examine these files to understand the application structure:
@app.py - Main Flask application with all routes and validation logic
@config.py - Configuration settings and validation constants
@templates/*.html - HTML templates for all 5 pages
</context>

<requirements>

<test_coverage>
Create comprehensive tests covering:

**1. Configuration and Setup Tests** (`test_config.py`)
- Verify configuration values are loaded correctly
- Test default configuration values
- Validate file path helpers

**2. Validation Function Tests** (`test_validation.py`)
- Email validation (valid/invalid formats)
- Phone number validation (international format, with/without spaces)
- Birth year validation (range checking, 4-digit requirement)
- ZIP code validation (numeric, length limits)
- File extension validation (allowed/disallowed types)
- Edge cases for all validators

**3. Route Tests** (`test_routes.py`)
- Test all 5 pages load correctly
- Test form submissions with valid data
- Test form submissions with invalid data
- Test redirect logic between pages
- Test session creation and session ID generation
- Test resume functionality (loading existing sessions)
- Test file upload endpoint
- Test file removal endpoint
- Test final submission

**4. Data Storage Tests** (`test_storage.py`)
- Test YAML file creation and reading
- Test data persistence across page transitions
- Test Unicode character handling (German umlauts: ü, ä, ö)
- Test application folder structure creation
- Test attachment folder management

**5. File Upload Tests** (`test_uploads.py`)
- Test successful file uploads
- Test file size validation (max 4 MB)
- Test file count limit (max 3 files)
- Test file type validation
- Test filename sanitization
- Test file removal
- Test edge cases (empty files, oversized files)

**6. Email Functionality Tests** (`test_email.py`)
- Test email sending with mocked SMTP
- Test resume link generation
- Test email content and formatting
- Test email failure handling

**7. Integration Tests** (`test_integration.py`)
- Test complete workflow from start to finish
- Test resume at each page
- Test data persistence throughout workflow
- Test multiple concurrent applications (different session IDs)

</test_coverage>

<test_fixtures>
Create pytest fixtures in `conftest.py`:
- `app` - Flask test app with testing configuration
- `client` - Flask test client for making requests
- `sample_application_data` - Sample YAML data for testing
- `temp_applications_dir` - Temporary directory for test data (auto-cleanup)
- `mock_mail` - Mocked Flask-Mail for email testing
- `sample_files` - Sample files for upload testing (PDF, image)
</test_fixtures>

<testing_best_practices>
- Use pytest fixtures for setup and teardown
- Mock external dependencies (SMTP, file system where appropriate)
- Test both success and failure scenarios
- Use parametrized tests for similar test cases with different inputs
- Ensure tests are isolated and don't affect each other
- Clean up test data after each test
- Use descriptive test names that explain what is being tested
- Add docstrings to complex tests
</testing_best_practices>

</requirements>

<implementation>

**Project Structure**
Create the following test structure:
```
./tests/
├── __init__.py
├── conftest.py              # Shared fixtures
├── test_config.py           # Configuration tests
├── test_validation.py       # Validation function tests
├── test_routes.py           # Route and form tests
├── test_storage.py          # YAML and file storage tests
├── test_uploads.py          # File upload tests
├── test_email.py            # Email functionality tests
├── test_integration.py      # End-to-end integration tests
└── fixtures/                # Test data files
    ├── sample.pdf           # Sample PDF for upload tests
    └── sample.jpg           # Sample image for upload tests
```

**Testing Configuration**
- Use `app.config['TESTING'] = True`
- Override `APPLICATIONS_FOLDER` to use a temporary directory
- Disable email sending by default (use mocks)
- Set predictable `SECRET_KEY` for testing

**Key Testing Patterns**

1. **Testing Routes with Flask Test Client**:
   - Use `client.get()` and `client.post()` to test endpoints
   - Check response status codes (200, 302 for redirects, etc.)
   - Verify flash messages appear correctly
   - Check redirects go to the correct pages

2. **Testing Data Persistence**:
   - Submit form data
   - Verify YAML file is created with correct data
   - Load data and verify it matches what was submitted
   - Test resume functionality loads the correct data

3. **Testing File Uploads**:
   - Use `BytesIO` to create test files
   - Set proper content type headers
   - Verify files are saved to correct location
   - Test file size and type validation

4. **Testing Session Flow**:
   - Track session IDs through the workflow
   - Verify `current_page` is updated correctly
   - Test resume redirects to appropriate page

**What to Avoid and Why**:
- Don't test Flask framework internals - focus on application logic
- Don't create actual files in the project directory - use temp directories to avoid cluttering the workspace
- Don't skip cleanup - use fixtures with teardown to remove test data, preventing test pollution
- Don't hardcode paths - use `app.config` values to ensure tests work in any environment
</implementation>

<output>
Create the following files with relative paths:

1. `./tests/__init__.py` - Empty file to make tests a package
2. `./tests/conftest.py` - Pytest configuration and shared fixtures
3. `./tests/test_config.py` - Configuration tests
4. `./tests/test_validation.py` - Validation function tests
5. `./tests/test_routes.py` - Route and form submission tests
6. `./tests/test_storage.py` - YAML and file storage tests
7. `./tests/test_uploads.py` - File upload functionality tests
8. `./tests/test_email.py` - Email sending tests with mocks
9. `./tests/test_integration.py` - End-to-end integration tests
10. `./tests/fixtures/sample.pdf` - Sample PDF file for testing (can be minimal)
11. `./tests/fixtures/sample.jpg` - Sample image file for testing (can be minimal)
12. `./pytest.ini` - Pytest configuration file
13. Update `./requirements.txt` - Add pytest and testing dependencies

Include in requirements.txt:
- pytest==7.4.3
- pytest-flask==1.3.0
- pytest-cov==4.1.0 (for coverage reports)
</output>

<verification>
Before declaring complete, verify your test suite:

1. **Run all tests and ensure they pass**:
   ```bash
   pytest -v
   ```

2. **Check test coverage**:
   ```bash
   pytest --cov=app --cov=config --cov-report=term-missing
   ```
   Aim for >80% coverage of app.py and config.py

3. **Test specific modules**:
   ```bash
   pytest tests/test_validation.py -v
   pytest tests/test_routes.py -v
   pytest tests/test_integration.py -v
   ```

4. **Verify fixtures work correctly**:
   - Test data is created in temporary directories
   - All temp data is cleaned up after tests
   - Mock email doesn't actually send emails

5. **Run a sample of critical test scenarios manually**:
   - Validation tests catch invalid inputs
   - Integration tests complete full workflow
   - File upload tests validate size and type limits

</verification>

<success_criteria>
- All test files created and organized properly
- pytest.ini configuration file exists
- requirements.txt updated with testing dependencies
- Comprehensive fixtures in conftest.py
- All validators have corresponding tests with edge cases
- All routes have tests for success and error scenarios
- File upload validation is thoroughly tested
- Integration test covers complete application workflow
- All tests pass when run with `pytest -v`
- Test coverage is >80% for core application files (app.py, config.py)
- Tests are isolated and can run in any order
- Test data is properly cleaned up after execution
- German text and Unicode characters are tested
- Mock email functionality works correctly
</success_criteria>