Development Guide¶

This guide covers testing, code quality, and contributing to the HOMEPOT project.

Development Setup¶

Quick Setup¶

# Clone and set up development environment
git clone https://github.com/brunel-opensim/homepot-client.git
cd homepot-client
./scripts/install.sh

# Activate development environment
source .venv/bin/activate

Manual Setup¶

# Create virtual environment
cd backend
pip install --upgrade pip
pip install -r requirements.txt

# Still in backend/ directory
pip install -e .

# Install additional development tools
pip install pytest pytest-cov black isort flake8 mypy bandit

Testing¶

Running Tests¶

# Run all tests with coverage
pytest

# Run specific test categories
pytest -m integration   # Integration tests only
pytest -m slow          # Performance tests only
pytest -m "not slow"    # All tests except slow ones (faster)

# Run with verbose output
pytest -v

# Run with detailed coverage report
pytest --cov=homepot --cov-report=html

Test Categories¶

Marker	Description	Count	Duration
`unit`	Unit tests for individual components	~15	< 1 min
`integration`	Integration tests across components	~3	2-5 min
`slow`	Performance and stress tests	~1	5-10 min
`api`	API endpoint tests	~8	1-2 min

Writing Tests¶

# Example unit test
import pytest
from homepot.database import DatabaseService

@pytest.mark.asyncio
async def test_site_creation():
    """Test site creation functionality."""
    db = DatabaseService()
    await db.initialize()

    site_data = {
        "site_id": "TEST_SITE_001",
        "name": "Test Site",
        "location": "Test Location"
    }

    result = await db.create_site(site_data)
    assert result["site_id"] == "TEST_SITE_001"
    assert result["name"] == "Test Site"

# Example integration test
@pytest.mark.integration
@pytest.mark.asyncio
async def test_complete_workflow():
    """Test complete site creation to device registration workflow."""
    # Test implementation here
    pass

Test Configuration¶

# pytest.ini
[tool:pytest]
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow-running tests
    api: API tests
addopts = 
    --strict-markers
    --cov=homepot
    --cov-report=term-missing
    --cov-fail-under=80

Code Quality¶

Automated Validation¶

```bash
black backend/src/homepot/ backend/tests/    # Code formatting
isort backend/src/homepot/ backend/tests/    # Import sorting
flake8 backend/src/homepot/ backend/tests/   # Style linting
mypy backend/src/homepot/                    # Type checking
bandit -r backend/src/homepot/               # Security scanning

### Code Formatting

```bash
**Format code:**
```bash
black backend/src/homepot/ backend/tests/

Check formatting without modifying:

black --check backend/src/homepot/ backend/tests/

Import sorting:

isort backend/src/homepot/ backend/tests/

### Type Checking

```bash
**Type checking:**
```bash
mypy backend/src/homepot/

Security scanning:

# Basic scan
bandit -r backend/src/homepot/

# Generate report
bandit -r backend/src/homepot/ -f json -o security-report.json

### Security Scanning

```bash
# Run security analysis
bandit -r backend/src/homepot/

# Generate security report
bandit -r backend/src/homepot/ -f json -o security-report.json

Development Workflow¶

Git Workflow¶

# Create feature branch
git checkout -b feature/new-feature

# Make changes and commit
git add .
git commit -m "Add new feature"

# Run tests before pushing
pytest
./scripts/validate-workflows.sh

# Push and create pull request
git push origin feature/new-feature

Pre-commit Hooks¶

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run hooks manually
pre-commit run --all-files

Development Scripts¶

Script	Purpose	Usage
`./scripts/install.sh`	Install dependencies	`./scripts/install.sh`
`.venv/bin/activate`	Activate environment	`source .venv/bin/activate`
`./scripts/validate-workflows.sh`	Run all quality checks (backend + frontend)	`./scripts/validate-workflows.sh`
`./scripts/validate-workflows.sh --frontend-only`	Run frontend checks only	`./scripts/validate-workflows.sh --frontend-only`
`./scripts/validate-workflows.sh --code-only`	Run Python code quality only	`./scripts/validate-workflows.sh --code-only`
`./scripts/build-docs.sh`	Build documentation	`./scripts/build-docs.sh`
`./scripts/test-docker.sh`	Test Docker setup	`./scripts/test-docker.sh`
`./scripts/query-db.sh`	Query database	`./scripts/query-db.sh`

Development Environment¶

IDE Configuration¶

VS Code Setup¶

{
  "python.defaultInterpreterPath": "./.venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "python.sortImports.args": ["--profile", "black"],
  "editor.formatOnSave": true
}

PyCharm Setup¶

Set interpreter to ./.venv/bin/python
Enable Black formatter in Tools → External Tools
Configure flake8 as code inspector
Set up pytest as test runner

Environment Variables¶

# Development environment variables
export HOMEPOT_ENV=development
export HOMEPOT_DEBUG=true
export HOMEPOT_LOG_LEVEL=DEBUG
export DATABASE__URL=postgresql://homepot_user:homepot_dev_password@localhost:5432/homepot_db

Development Database¶

# Create development database
./scripts/init-postgresql.sh

# Verify database content
./scripts/query-db.sh count

# Reset database
./scripts/init-postgresql.sh

Contributing¶

Contribution Guidelines¶

Fork the repository
Create a feature branch
Make changes with tests
Run quality checks
Submit pull request

Code Standards¶

PEP 8 compliance (enforced by flake8)
Type hints for all public APIs
Docstrings for all public functions/classes
Test coverage > 80% for new code
No security vulnerabilities (bandit)

Documentation¶

def create_site(site_data: Dict[str, Any]) -> Dict[str, Any]:
    """Create a new POS site.

    Args:
        site_data: Site configuration including site_id, name, location

    Returns:
        Created site data with timestamps

    Raises:
        ValueError: If site_id already exists
        ValidationError: If site_data is invalid

    Example:
        >>> site = create_site({
        ...     "site_id": "STORE_001",
        ...     "name": "Downtown Store",
        ...     "location": "123 Main St"
        ... })
        >>> print(site["site_id"])
        STORE_001
    """

Pull Request Template¶

## Description
Brief description of changes

## Type of Change
- Bug fix
- New feature
- Breaking change
- Documentation update

## Testing
- Tests pass locally
- New tests added
- Manual testing performed

## Checklist
- Code follows style guidelines
- Self-review completed
- Documentation updated
- No new security vulnerabilities

Debugging¶

Development Server¶

# Run with debug mode
HOMEPOT_DEBUG=true python -m homepot.main

# Run with specific log level
HOMEPOT_LOG_LEVEL=DEBUG python -m homepot.main

# Run with pdb debugger
python -m pdb -m homepot.main

Database Debugging¶

Use the provided helper script to inspect the database state without needing to memorize connection strings.

# List all tables and row counts
./scripts/query-db.sh count

# View specific data
./scripts/query-db.sh sites
./scripts/query-db.sh devices

# View relationship data
./scripts/query-db.sh site_devices RESTAURANT_001

# Run custom SQL queries
./scripts/query-db.sh sql "SELECT * FROM sites WHERE location LIKE '%Main St%'"

# View table schema
./scripts/query-db.sh schema sites

API Debugging¶

# Test API endpoints with verbose output
curl -v http://localhost:8000/health

# Use HTTPie for better output
pip install httpie
http GET localhost:8000/sites

# Monitor API logs
tail -f logs/backend.log | grep -i error

# Monitor access logs (HTTP requests)
tail -f logs/backend.out

Performance¶

Profiling¶

# Profile application startup
python -m cProfile -o profile.stats -m homepot.main

# Analyze profile results
python -c "
import pstats
p = pstats.Stats('profile.stats')
p.sort_stats('cumulative').print_stats(20)
"

Memory Monitoring¶

# Monitor memory usage
pip install memory-profiler
python -m memory_profiler -m homepot.main

# Generate memory reports
mprof run python -m homepot.main
mprof plot

Load Testing¶

# Install load testing tools
pip install locust

# Run load tests
locust -f backend/tests/load_test.py --host=http://localhost:8000

Troubleshooting¶

Common Development Issues¶

Import Errors:

# Reinstall in development mode
pip install -e .

# Check Python path
python -c "import sys; print(sys.path)"

Test Failures:

# Run specific failing test
pytest backend/tests/test_specific.py::test_function -v

# Debug test with pdb
pytest backend/tests/test_specific.py::test_function --pdb

Database Issues:

# Reset development database
rm homepot.db
python -m homepot.main

Getting Help¶

Documentation: Check the docs/ directory
Issues: GitHub Issues
Discussions: GitHub Discussions
Contact: Reach out to maintainers

Next: Learn about Deployment Guide for production deployment with Docker.