github/dawarich
1
1
Fork 0
mirror of https://github.com/Freika/dawarich.git synced 2026-01-09 20:38:01 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
tests/playwright
dawarich/dawarich_user_scenarios.md
Eugene Burmakin f9c93c0d3c Add E2E tests for Dawarich
2025-07-12 15:24:10 +02:00

16 KiB
Raw Permalink Blame History

Dawarich User Scenarios Documentation

Overview

Dawarich is a self-hosted location history tracking application that allows users to import, visualize, and analyze their location data. This document describes all user scenarios for comprehensive test coverage.

Application Context

  • Purpose: Self-hosted alternative to Google Timeline/Location History
  • Tech Stack: Rails 8, PostgreSQL, Hotwire (Turbo/Stimulus), Tailwind CSS with DaisyUI
  • Key Features: Location tracking, data visualization, import/export, statistics, visits detection
  • Deployment: Docker-based with self-hosted and cloud options

1. Authentication & User Management

1.1 User Registration (Non-Self-Hosted Mode)

Scenario: New user registration process

  • Entry Point: Home page → Sign up link
  • Steps:
    1. Navigate to registration form
    2. Fill in email, password, password confirmation
    3. Complete CAPTCHA (if enabled)
    4. Submit registration
    5. Receive confirmation (if email verification enabled)
  • Validation: Email format, password strength, password confirmation match
  • Success: User created, redirected to sign-in or dashboard

1.2 User Sign In/Out

Scenario: User authentication workflow

  • Entry Point: Home page → Sign in link
  • Steps:
    1. Navigate to sign-in form
    2. Enter email and password
    3. Optionally check "Remember me"
    4. Submit login
    5. Successful login redirects to map page
  • Demo Mode: Special demo credentials (demo@dawarich.app / password)
  • Sign Out: User can sign out from dropdown menu

1.3 Password Management

Scenario: Password reset and change functionality

  • Forgot Password:
    1. Click "Forgot password" link
    2. Enter email address
    3. Receive reset email
    4. Follow reset link
    5. Set new password
  • Change Password (when signed in):
    1. Navigate to account settings
    2. Provide current password
    3. Enter new password and confirmation
    4. Save changes

1.4 Account Settings

Scenario: User account management

  • Entry Point: User dropdown → Account
  • Actions:
    1. Update email address (requires current password)
    2. Change password
    3. View API key
    4. Generate new API key
    5. Theme selection (light/dark)
  • Self-Hosted: Limited registration options

2. Map Functionality & Visualization

2.1 Main Map Interface

Scenario: Core location data visualization

  • Entry Point: Primary navigation → Map
  • Features:
    1. Interactive Leaflet map with multiple tile layers
    2. Time range selector (date/time inputs)
    3. Quick time range buttons (Today, Last 7 days, Last month)
    4. Navigation arrows for day-by-day browsing
    5. Real-time distance and points count display

2.2 Map Layers & Controls

Scenario: Map customization and layer management

  • Base Layers:
    1. Switch between OpenStreetMap and OpenTopo
    2. Custom tile layer configuration
  • Overlay Layers:
    1. Toggle points display
    2. Toggle route lines
    3. Toggle heatmap
    4. Toggle fog of war
    5. Toggle areas
    6. Toggle visits
  • Layer Control: Expandable/collapsible layer panel

2.3 Map Data Display

Scenario: Location data visualization options

  • Points Rendering:
    1. Raw mode (all points)
    2. Simplified mode (filtered by time/distance)
    3. Point clicking reveals details popup
    4. Battery level, altitude, velocity display
  • Routes:
    1. Polyline connections between points
    2. Speed-colored routes option
    3. Configurable route opacity
    4. Route segment distance display

2.4 Map Settings & Configuration

Scenario: Map behavior customization

  • Settings Available:
    1. Route opacity (0-100%)
    2. Meters between routes (distance threshold)
    3. Minutes between routes (time threshold)
    4. Fog of war radius
    5. Speed color scale customization
    6. Points rendering mode
  • Help Modals: Contextual help for each setting

3. Location Data Import

3.1 Manual File Import

Scenario: Import location data from various sources

  • Entry Point: Navigation → My data → Imports
  • Supported Sources:
    1. Google Semantic History (JSON files)
    2. Google Records (Records.json)
    3. Google Phone Takeout (mobile device JSON)
    4. OwnTracks (.rec files)
    5. GeoJSON files
    6. GPX track files
  • Process:
    1. Select source type
    2. Choose file(s) via file picker
    3. Upload and process (background job)
    4. Receive completion notification

3.2 Automatic File Watching

Scenario: Automatic import from watched directories

  • Setup: Files placed in /tmp/imports/watched/USER@EMAIL.TLD/
  • Process: System scans hourly for new files
  • Supported Formats: GPX, JSON, REC files
  • Notification: User receives import completion notifications

3.3 Photo Integration Import

Scenario: Import location data from photo EXIF data

  • Immich Integration:
    1. Configure Immich URL and API key in settings
    2. Trigger import job
    3. System extracts GPS data from photos
    4. Creates location points from photo metadata
  • Photoprism Integration:
    1. Configure Photoprism URL and API key
    2. Similar process to Immich
    3. Supports different date ranges

3.4 Import Management

Scenario: View and manage import history

  • Import List: View all imports with status
  • Import Details: Points count, processing status, errors
  • Import Actions: View details, delete imports
  • Progress Tracking: Real-time progress updates via WebSocket

4. Data Export

4.1 Export Creation

Scenario: Export location data in various formats

  • Entry Point: Navigation → My data → Exports
  • Export Types:
    1. GeoJSON format (default)
    2. GPX format
    3. Complete user data archive (ZIP)
  • Process:
    1. Select export format
    2. Choose date range (optional)
    3. Submit export request
    4. Background processing
    5. Notification when complete

4.2 Export Management

Scenario: Manage created exports

  • Export List: View all exports with details
  • Export Actions:
    1. Download completed exports
    2. Delete old exports
    3. View export status
  • File Information: Size, creation date, download links

4.3 Complete Data Export

Scenario: Export all user data for backup/migration

  • Trigger: Settings → Users → Export data
  • Content: All user data, settings, files in ZIP format
  • Use Case: Account migration, data backup
  • Process: Background job, notification on completion

5. Statistics & Analytics

5.1 Statistics Dashboard

Scenario: View travel statistics and analytics

  • Entry Point: Navigation → Stats
  • Key Metrics:
    1. Total distance traveled
    2. Total tracked points
    3. Countries visited
    4. Cities visited
    5. Reverse geocoding statistics
  • Display: Cards with highlighted numbers and units

5.2 Yearly/Monthly Breakdown

Scenario: Detailed statistics by time period

  • View Options:
    1. Statistics by year
    2. Monthly breakdown within years
    3. Distance traveled per period
    4. Points tracked per period
  • Actions: Update statistics (background job)

5.3 Statistics Management

Scenario: Update and manage statistics

  • Manual Updates:
    1. Update all statistics
    2. Update specific year/month
    3. Background job processing
  • Automatic Updates: Triggered by data imports

6. Trips Management

6.1 Trip Creation

Scenario: Create and manage travel trips

  • Entry Point: Navigation → Trips → New trip
  • Trip Properties:
    1. Trip name
    2. Start date/time
    3. End date/time
    4. Notes (rich text)
  • Validation: Date ranges, required fields

6.2 Trip Visualization

Scenario: View trip details and route

  • Trip View:
    1. Interactive map with trip route
    2. Trip statistics (distance, duration)
    3. Countries visited during trip
    4. Photo integration (if configured)
  • Photo Display: Grid layout with links to photo sources

6.3 Trip Management

Scenario: Edit and manage existing trips

  • Trip List: Paginated view of all trips
  • Trip Actions:
    1. Edit trip details
    2. Delete trips
    3. View trip details
  • Background Processing: Distance and route calculations

7. Visits & Places (Beta Feature)

7.1 Visit Suggestions

Scenario: Automatic visit detection and suggestions

  • Process: Background job analyzes location data
  • Detection: Identifies places where user spent time
  • Suggestions: Creates suggested visits for review
  • Notifications: User receives visit suggestion notifications

7.2 Visit Management

Scenario: Review and manage visit suggestions

  • Entry Point: Navigation → My data → Visits & Places
  • Visit States:
    1. Suggested (pending review)
    2. Confirmed (accepted)
    3. Declined (rejected)
  • Actions: Confirm, decline, or edit visits
  • Filtering: View by status, order by date

7.3 Places Management

Scenario: Manage detected places

  • Place List: All places created by visit suggestions
  • Place Details: Name, coordinates, creation date
  • Actions: Delete places (deletes associated visits)
  • Integration: Places linked to visits

7.4 Areas Creation

Scenario: Create custom areas for visit detection

  • Map Interface: Draw areas on map
  • Area Properties:
    1. Name
    2. Radius
    3. Coordinates (center point)
  • Purpose: Improve visit detection accuracy

8. Points Management

8.1 Points List

Scenario: View and manage individual location points

  • Entry Point: Navigation → My data → Points
  • Display: Paginated table with point details
  • Point Information:
    1. Timestamp
    2. Coordinates
    3. Accuracy
    4. Source import
  • Filtering: Date range, import source

8.2 Point Actions

Scenario: Individual point management

  • Point Details: Click point for popup with full details
  • Actions:
    1. Delete individual points
    2. Bulk delete points
    3. View point source
  • Map Integration: Points clickable on map

9. Notifications System

9.1 Notification Types

Scenario: System notifications for various events

  • Import Notifications:
    1. Import completed
    2. Import failed
    3. Import progress updates
  • Export Notifications:
    1. Export completed
    2. Export failed
  • System Notifications:
    1. Visit suggestions available
    2. Statistics updates completed
    3. Background job failures

9.2 Notification Management

Scenario: View and manage notifications

  • Entry Point: Bell icon in navigation
  • Notification List: All notifications with timestamps
  • Actions:
    1. Mark as read
    2. Mark all as read
    3. Delete notifications
    4. Delete all notifications
  • Display: Badges for unread count

10. Settings & Configuration

10.1 Integration Settings

Scenario: Configure external service integrations

  • Entry Point: Navigation → Settings → Integrations
  • Immich Integration:
    1. Configure Immich URL
    2. Set API key
    3. Test connection
  • Photoprism Integration:
    1. Configure Photoprism URL
    2. Set API key
    3. Test connection

10.2 Map Settings

Scenario: Configure map appearance and behavior

  • Entry Point: Settings → Map
  • Options:
    1. Custom tile layer URL
    2. Map layer name
    3. Distance unit (km/miles)
    4. Tile usage statistics
  • Preview: Real-time map preview

10.3 User Settings

Scenario: Personal preferences and account settings

  • Theme: Light/dark mode toggle
  • API Key: View and regenerate API key
  • Visits Settings: Enable/disable visit suggestions
  • Route Settings: Default route appearance

11. Admin Features (Self-Hosted Only)

11.1 User Management

Scenario: Admin user management in self-hosted mode

  • Entry Point: Settings → Users (admin only)
  • User Actions:
    1. Create new users
    2. Edit user details
    3. Delete users
    4. View user statistics
  • User Creation: Email and password setup

11.2 Background Jobs Management

Scenario: Admin control over background processing

  • Entry Point: Settings → Background Jobs
  • Job Types:
    1. Reverse geocoding jobs
    2. Statistics calculation
    3. Visit suggestion jobs
  • Actions: Start/stop background jobs, view job status

11.3 System Administration

Scenario: System-level administration

  • Sidekiq Dashboard: Background job monitoring
  • System Settings: Global configuration options
  • User Data Management: Export/import user data

12. API Functionality

12.1 Location Data API

Scenario: Programmatic location data submission

  • Endpoints: RESTful API for location data
  • Authentication: API key based
  • Supported Apps:
    1. Dawarich iOS app
    2. Overland
    3. OwnTracks
    4. GPSLogger
    5. Custom applications

12.2 Data Retrieval API

Scenario: Retrieve location data via API

  • Use Cases: Third-party integrations, mobile apps
  • Data Formats: JSON, GeoJSON
  • Authentication: API key required

13. Error Handling & Edge Cases

13.1 Import Errors

Scenario: Handle various import failure scenarios

  • File Format Errors: Unsupported or corrupted files
  • Processing Errors: Background job failures
  • Network Errors: Failed downloads or API calls
  • User Feedback: Error notifications with details

13.2 System Errors

Scenario: Handle system-level errors

  • Database Errors: Connection issues, constraints
  • Storage Errors: File system issues
  • Memory Errors: Large data processing
  • User Experience: Graceful error messages

13.3 Data Validation

Scenario: Validate user input and data integrity

  • Coordinate Validation: Valid latitude/longitude
  • Time Validation: Logical timestamp values
  • File Validation: Supported formats and sizes
  • User Input: Form validation and sanitization

14. Performance & Scalability

14.1 Large Dataset Handling

Scenario: Handle users with large amounts of location data

  • Map Performance: Efficient rendering of many points
  • Data Processing: Batch processing for imports
  • Memory Management: Streaming for large files
  • User Experience: Progress indicators, pagination

14.2 Background Processing

Scenario: Asynchronous task handling

  • Job Queues: Sidekiq for background jobs
  • Progress Tracking: Real-time job status
  • Error Recovery: Retry mechanisms
  • User Feedback: Job completion notifications

15. Mobile & Responsive Design

15.1 Mobile Interface

Scenario: Mobile-optimized user experience

  • Responsive Design: Mobile-first approach
  • Touch Interactions: Map gestures, mobile-friendly controls
  • Mobile Navigation: Collapsible menus
  • Performance: Optimized for mobile devices

15.2 Cross-Platform Compatibility

Scenario: Consistent experience across devices

  • Browser Support: Modern browser compatibility
  • Device Support: Desktop, tablet, mobile
  • Feature Parity: Full functionality across platforms

Test Scenarios Priority

High Priority (Core Functionality)

  1. User authentication (sign in/out)
  2. Map visualization with basic controls
  3. Data import (at least one source type)
  4. Basic settings configuration
  5. Point display and interaction

Medium Priority (Extended Features)

  1. Trip management
  2. Visit suggestions and management
  3. Data export
  4. Statistics viewing
  5. Notification system

Low Priority (Advanced Features)

  1. Admin functions
  2. API functionality
  3. Complex map settings
  4. Background job management
  5. Error handling edge cases

Notes for Test Implementation

  1. Test Data: Use factory-generated test data for consistency
  2. API Testing: Include both UI and API endpoint testing
  3. Background Jobs: Test asynchronous processing
  4. File Handling: Test various file formats and sizes
  5. Responsive Testing: Include mobile viewport testing
  6. Performance Testing: Test with large datasets
  7. Error Scenarios: Include negative test cases
  8. Browser Compatibility: Test across different browsers
Reference in New Issue View Git Blame Copy Permalink