gitea-admin/gh-christianlouis-docuelevate

Files

T

copilot-swe-agent[bot] 9795a3966a docs: add comprehensive test setup documentation and auth integration tests

- Add detailed test setup section to CONTRIBUTING.md explaining environment configuration
- Add testing section to README.md with quick start guide
- Create test_api_auth_enabled.py with 11 new integration tests for auth configuration
- Document that tests automatically configure required environment variables (no manual setup)
- Explain AUTH_ENABLED and SESSION_SECRET configuration for tests
- Include examples of testing with authentication enabled
- Reference integration test documentation for Docker-based tests

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

2026-02-10 15:50:13 +00:00

10 KiB

Raw Blame History

Contributing to DocuElevate

Thank you for your interest in contributing to DocuElevate! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

By participating in this project, you agree to abide by the Code of Conduct.

How to Contribute

Reporting Bugs

If you find a bug in the codebase, please submit an issue on GitHub with:

A clear title and description
Steps to reproduce the issue
Expected behavior
Actual behavior
Environment information (OS, Docker version, etc.)

Feature Requests

We welcome feature requests! Please submit an issue with:

A clear title and description
The problem the feature would solve
Any ideas you have for implementing the feature

Pull Requests

Fork the repository
Create a new branch for your changes
Make your changes
Follow conventional commit format (see below)
Run the tests to ensure everything works
Submit a pull request with a clear description of the changes

Commit Message Format

DocuElevate follows the Conventional Commits specification for commit messages. This enables automatic version bumping and changelog generation.

Format

<type>(<scope>): <subject>

<body>

<footer>

Type

Must be one of the following:

feat: A new feature (triggers minor version bump)
fix: A bug fix (triggers patch version bump)
docs: Documentation only changes
style: Changes that don't affect code meaning (formatting, etc.)
refactor: Code change that neither fixes a bug nor adds a feature
perf: Performance improvement (triggers patch version bump)
test: Adding or updating tests
build: Changes to build system or dependencies
ci: Changes to CI configuration files and scripts
chore: Other changes that don't modify src or test files

Scope (Optional)

The scope should be the name of the affected module or area:

api - REST API changes
ui - Frontend/UI changes
auth - Authentication changes
storage - Storage provider changes
ocr - OCR processing changes
tasks - Celery task changes
config - Configuration changes

Subject

The subject contains a succinct description of the change:

Use imperative, present tense: "change" not "changed" nor "changes"
Don't capitalize first letter
No period (.) at the end

Breaking Changes

For breaking changes, add ! after the type/scope or include BREAKING CHANGE: in the footer:

feat!: redesign authentication API

BREAKING CHANGE: The /api/auth endpoint now requires OAuth2 tokens instead of API keys.

This triggers a major version bump.

Examples

feat(storage): add support for Amazon S3 storage provider

Add S3StorageProvider class with upload, download, and delete operations.
Includes configuration options for bucket name, region, and credentials.

Closes #123

fix(ocr): handle PDF files without text layer

Previously, PDFs without existing text layers would fail silently.
Now properly processes them through Azure Document Intelligence.

Fixes #456

docs: update deployment guide with Docker Compose setup

Added step-by-step instructions for deploying with Docker Compose,
including environment variable configuration and service dependencies.

chore: update dependencies to fix security vulnerabilities

Updated authlib to 1.6.5+ and starlette to 0.49.1+

Versioning and Releases

DocuElevate uses semantic-release for automated version management and releases:

Releases are automated: When PRs are merged to main, semantic-release analyzes commit messages and automatically:
- Determines the next version number
- Updates the VERSION file
- Generates/updates CHANGELOG.md
- Creates a Git tag with v prefix (e.g., v0.6.0)
- Creates a GitHub Release with auto-generated notes
- Triggers Docker image builds with the new version tag
Version Bumps:
- feat: commits → minor version bump (0.5.0 → 0.6.0)
- fix: or perf: commits → patch version bump (0.5.0 → 0.5.1)
- feat!: or BREAKING CHANGE: → major version bump (0.5.0 → 1.0.0)
- Other commit types (docs, chore, etc.) → no version bump
Manual Version Changes: Do NOT manually edit VERSION or CHANGELOG.md - these are managed by semantic-release

Pull Request Checklist

Before submitting a pull request:

Code follows the project style guide (Black, isort, flake8)
Commit messages follow conventional commit format
Tests added/updated for new functionality
Documentation updated if user-facing changes
No manual edits to VERSION or CHANGELOG.md
All tests pass locally
Pre-commit hooks pass
Security scan passes (if applicable)

Development Environment

Setting Up Your Environment

# Clone the repository
git clone https://github.com/christianlouis/DocuElevate.git
cd DocuElevate

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

Running Tests

DocuElevate has comprehensive test coverage including unit tests, integration tests, and end-to-end tests. Tests are automatically configured with the necessary environment variables.

Quick Test Commands

# Run all tests (default configuration)
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=app --cov-report=term-missing

# Run only unit tests (fast, no Docker required)
pytest -m unit

# Run only integration tests
pytest -m integration

# Run specific test file
pytest tests/test_api.py -v

Test Environment Configuration

Tests automatically configure the required environment variables in tests/conftest.py:

DATABASE_URL: Uses SQLite in-memory database for fast, isolated tests
AUTH_ENABLED: Set to False by default for simpler unit tests
SESSION_SECRET: Pre-configured with a valid 32+ character secret for tests that need it
OPENAI_API_KEY, AZURE_AI_KEY, etc.: Pre-configured with test values

No manual environment setup is needed to run tests!

Testing with Authentication Enabled

Some tests specifically verify authentication behavior with AUTH_ENABLED=True. These tests:

Use @patch("app.auth.AUTH_ENABLED", True) to enable auth for specific tests
Properly configure SESSION_SECRET (already set in conftest.py)
Mock user sessions to test protected endpoints
Verify login redirects and access control

Example:

from unittest.mock import patch

@pytest.mark.integration
def test_protected_endpoint_with_auth(client):
    """Test endpoint requires authentication when auth is enabled."""
    with patch("app.auth.AUTH_ENABLED", True):
        # Test will verify redirect to /login
        response = client.get("/protected-page")
        assert response.status_code == 302

Integration Tests with Docker

Some tests require Docker to spin up real infrastructure (PostgreSQL, Redis, WebDAV, etc.):

# Run integration tests that need Docker
pytest -m requires_docker -v

# Run end-to-end tests with full stack
pytest -m e2e -v

See tests/README_INTEGRATION_TESTS.md for detailed information about integration testing.

Test Markers

Tests are organized using pytest markers:

@pytest.mark.unit - Fast unit tests with mocks
@pytest.mark.integration - Integration tests with some real services
@pytest.mark.e2e - Full end-to-end tests
@pytest.mark.requires_docker - Requires Docker to run
@pytest.mark.slow - Tests that take significant time
@pytest.mark.security - Security-related tests

Running Tests in CI

Tests run automatically in GitHub Actions for all pull requests. The CI environment:

Installs all dependencies from requirements-dev.txt
Runs pytest with coverage
Uploads coverage reports to Codecov
Fails the build if tests don't pass or coverage drops

Code Style

We use:

Black for Python code formatting (line length: 120)
Flake8 for linting
isort for import sorting (Black-compatible profile)

# Format code
black .

# Check linting
flake8

# Sort imports
isort .

Project Structure

DocuElevate/
├── app/               # Main application code
│   ├── api/          # REST API endpoints (organized by feature)
│   ├── tasks/        # Celery background tasks
│   ├── views/        # UI routes and template rendering
│   ├── utils/        # Utility functions and helpers
│   ├── config.py     # Configuration management (Pydantic)
│   ├── database.py   # Database setup and session management
│   ├── models.py     # SQLAlchemy models
│   ├── main.py       # FastAPI app initialization
│   └── auth.py       # Authentication logic
├── frontend/         # Frontend assets
│   ├── static/       # CSS, JavaScript, images
│   └── templates/    # Jinja2 HTML templates
├── tests/            # Test suite
├── docs/             # User and developer documentation
├── migrations/       # Alembic database migrations
└── docker/           # Docker configuration files

📚 Additional Resources

Documentation

AGENTIC_CODING.md - Comprehensive guide for AI agents and developers
README.md - Project overview and quickstart
ROADMAP.md - Future features and long-term vision
MILESTONES.md - Release planning and versioning
TODO.md - Current tasks and priorities
SECURITY.md - Security policy
SECURITY_AUDIT.md - Security findings and improvements

Testing

All new features must include tests
Aim for 80% code coverage
See AGENTIC_CODING.md#testing-strategy for detailed testing guidelines

Security

Never commit secrets or credentials
Follow guidelines in SECURITY_AUDIT.md
Report security issues per SECURITY.md

🤝 Getting Help

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and community support
Documentation: Check docs/ directory for guides

Thank you for contributing to DocuElevate!

10 KiB Raw Blame History