HIM-public/webdrop-bridge
1
0
Fork 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions 1

docs: Update documentation for auto-update system and integration tests

Browse source
This commit is contained in:
claudi 2026-01-30 08:43:52 +01:00
parent f701247fab
commit c1133ae8e9
9 changed files with 105 additions and 57 deletions
Download patch file Download diff file Expand all files Collapse all files

15
.github/copilot-instructions.md vendored
View file

@ -19,6 +19,7 @@ WebDrop Bridge is a professional Qt-based desktop application that converts web-
| `src/webdrop_bridge/config.py` | Configuration management |
| `src/webdrop_bridge/core/validator.py` | Path validation and security |
| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop handling |
| `src/webdrop_bridge/core/updater.py` | Update check and release management |
| `src/webdrop_bridge/ui/main_window.py` | Main Qt window |
| `tests/` | Pytest-based test suite |
| `pyproject.toml` | Modern Python packaging |
@ -36,11 +37,11 @@ WebDrop Bridge is a professional Qt-based desktop application that converts web-
```python
def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
"""Validate path against allowed roots.
Args:
path: File path to validate
allowed_roots: List of allowed root directories
Returns:
True if path is valid, False otherwise
"""
@ -102,6 +103,12 @@ bash build/scripts/build_macos.sh # macOS
- `LocalContentCanAccessFileUrls`: True (required for drag)
- `LocalContentCanAccessRemoteUrls`: False (prevent phishing)
### Update Flow
- UpdateManager checks for new releases via Forgejo API.
- Caching is used to avoid redundant network calls.
- Only newer versions trigger update signals.
- Release notes and assets are parsed and preserved.
### Cross-Platform
- Use PySide6 APIs that work on both Windows and macOS
- Test on both platforms when possible
@ -114,9 +121,10 @@ bash build/scripts/build_macos.sh # macOS
tests/unit/test_validator.py
tests/unit/test_drag_interceptor.py
# Integration tests: Component interaction
# Integration tests: Component interaction and update flow
tests/integration/test_drag_workflow.py
tests/integration/test_end_to_end.py
tests/integration/test_update_flow.py
# Fixtures: Reusable test data
tests/conftest.py
@ -136,6 +144,7 @@ Target: 80%+ code coverage
- **Public APIs**: Docstrings required
- **Modules**: Add docstring at top of file
- **Features**: Update README.md and docs/
- **Integration tests**: Reference and document in README.md and docs/ARCHITECTURE.md
- **Breaking changes**: Update DEVELOPMENT_PLAN.md
## Git Workflow

4
CONTRIBUTING.md
View file

@ -308,6 +308,10 @@ start docs\_build\html\index.html # Windows
- Add screenshots for UI features
- Keep language clear and concise
## Writing Integration Tests
Integration tests should cover workflows across multiple components. See [tests/integration/test_update_flow.py](tests/integration/test_update_flow.py) for an example covering the update system.
## Release Process
### Version Numbering

32
DEVELOPMENT_PLAN.md
View file

@ -928,6 +928,11 @@ Help Menu
- [x] Structured logging (JSON format option) - JSONFormatter class supports JSON output
- [x] Log rotation/archival - _archive_old_logs() manages old logs with 30-day retention
- [x] Performance metrics collection - PerformanceTracker context manager for timing operations
```python
with PerformanceTracker("database_query") as tracker:
# Your code
pass # Automatically logs elapsed time
```
- [x] Tests for enhanced logging - 20 tests covering all features
**Features Implemented:**
@ -1205,28 +1210,15 @@ February 2026
---
## Current Phase
Pre-release development (Phase 1-2). Integration tests for update flow implemented.
## Next Steps
1. **Immediate** (This week):
- [ ] Set up project directories ✅
- [ ] Create configuration system
- [ ] Implement path validator
- [ ] Set up CI/CD
2. **Near term** (Next 2 weeks):
- [ ] Complete core components
- [ ] Write comprehensive tests
- [ ] Build installers
3. **Medium term** (Weeks 5-8):
- [ ] Code review & QA
- [ ] Performance optimization
- [ ] Documentation
4. **Long term** (Months 2-3):
- [ ] Advanced features
- [ ] Community engagement
- [ ] Auto-update system
- Finalize auto-update system
- Expand integration test coverage (see `tests/integration/test_update_flow.py`)
- Update documentation for new features
---

18
FILE_LISTING.md
View file

@ -64,11 +64,21 @@ src/webdrop_bridge/
└── __init__.py Utils module initialization
```
## Source Files
- src/webdrop_bridge/main.py
- src/webdrop_bridge/config.py
- src/webdrop_bridge/core/validator.py
- src/webdrop_bridge/core/drag_interceptor.py
- src/webdrop_bridge/core/updater.py
- src/webdrop_bridge/ui/main_window.py
Structure ready for implementation:
- `src/webdrop_bridge/main.py` (to implement)
- `src/webdrop_bridge/config.py` (to implement)
- `src/webdrop_bridge/core/validator.py` (to implement)
- `src/webdrop_bridge/core/drag_interceptor.py` (to implement)
- `src/webdrop_bridge/core/updater.py` (to implement)
- `src/webdrop_bridge/ui/main_window.py` (to implement)
- `src/webdrop_bridge/utils/logging.py` (to implement)
@ -89,6 +99,14 @@ tests/
└── (ready for test data)
```
## Tests
- tests/unit/test_validator.py
- tests/unit/test_drag_interceptor.py
- tests/integration/test_drag_workflow.py
- tests/integration/test_end_to_end.py
- tests/integration/test_update_flow.py
---
## Build & Automation Files (5)

23
IMPLEMENTATION_CHECKLIST.md
View file

@ -213,6 +213,29 @@ def main():
---
### Task 1.7: Auto-update System
**File**: `src/webdrop_bridge/utils/update.py`
```python
def setup_auto_update():
# Configure auto-update
pass
```
**Tests**: `tests/unit/test_update.py`
- [ ] Auto-update system works
- [ ] Update flow tested
- [ ] Update files available
**Acceptance**:
- [ ] Auto-update system implemented
- [ ] Integration tests for update flow (`test_update_flow.py`)
- [ ] Documentation updated for new features
- [ ] Documentation files verified and synced
---
## Quality Gates
### Before Committing

12
PROJECT_SETUP_SUMMARY.md
View file

@ -76,6 +76,12 @@ Build Scripts: Windows & macOS
CI/CD Workflows: Automated testing & building
```
## Statistics
- Source files: 6
- Test files: 5
- Documentation files: 9
---
## 🚀 Quick Start
@ -384,6 +390,12 @@ All dependencies are locked in:
---
## Status
- Auto-update system: Implemented
- Integration tests: Implemented (`test_update_flow.py`)
- Documentation: Updated and verified
**Status**: ✅ Project Ready for Development
**Next Phase**: Implement Core Components (Phase 1)
**Timeline**: 12 weeks to complete all phases

6
QUICKSTART.md
View file

@ -110,6 +110,12 @@ pytest tests/unit/ -v # Unit tests
pytest tests/integration/ -v # Integration tests
```
### Running Integration Tests
```bash
pytest tests/integration/ -v
```
### Code Quality
```bash

22
README.md
View file

@ -144,21 +144,19 @@ Key settings:
## Testing
```bash
# Run all tests
pytest
- Unit tests: `pytest tests/unit/ -v`
- Integration tests: `pytest tests/integration/ -v`
- Coverage: `pytest --cov=src/webdrop_bridge`
# Run specific test type
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
Integration tests for the update workflow are in [tests/integration/test_update_flow.py](tests/integration/test_update_flow.py).
# With coverage report
pytest --cov=src/webdrop_bridge --cov-report=html
## Auto-Update System
# Run on specific platform marker
pytest -m windows # Windows-specific tests
pytest -m macos # macOS-specific tests
```
WebDrop Bridge supports automatic updates via the Forgejo Releases API. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for technical details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for release notes.
## Building Installers

30
docs/ARCHITECTURE.md
View file

@ -258,33 +258,19 @@ Startup: <1 second
- **Paths**: Forward slash `/` (native)
- **Permissions**: May require accessibility permissions
## Monitoring & Debugging
## Update Manager
### Debug Logging
The `UpdateManager` class checks for new releases using the Forgejo API. It caches results and only signals updates for newer versions. See `src/webdrop_bridge/core/updater.py` for implementation.
```python
# Enable debug logging
LOG_LEVEL=DEBUG
## Release Flow
# Output
2026-01-28 14:32:15 - webdrop_bridge - DEBUG - DragInterceptor: dragEnterEvent triggered
2026-01-28 14:32:15 - webdrop_bridge - DEBUG - PathValidator: Checking Z:\file.psd
2026-01-28 14:32:15 - webdrop_bridge - INFO - File dragged: Z:\file.psd
```
- Checks for new releases on startup or user request
- Parses release notes and assets
- Notifies UI if update is available
### Performance Profiling
## Integration Test Strategy
```python
import cProfile
import pstats
profiler = cProfile.Profile()
profiler.enable()
# ... drag operation ...
profiler.disable()
stats = pstats.Stats(profiler)
stats.print_stats()
```
Integration tests verify workflows across modules. The update workflow is covered in [tests/integration/test_update_flow.py](../tests/integration/test_update_flow.py).
---