Back to Projects

RouteRunner

Project Motivation & Problem Statement

In IoT and location-based services, devices are grouped into geographic clusters for efficient alert management and data aggregation. When devices move beyond cluster boundaries, the system must dynamically re-cluster them and trigger appropriate alerts. Testing this clustering logic against a live API-validating alert delivery, SNS notifications, and SQS message queuing-is complex and error-prone when done manually. RouteRunner (Genie Test Rig) was built as a comprehensive GUI-based test platform that automates validation of device clustering behavior, API alert delivery, and AWS messaging infrastructure for the Genie location services platform.

Technical Approach

1. Modular Application Architecture

Built a clean, modular Python application with separated concerns:

  • app/genie_api.py: Core API client for device registration, location updates, and cluster management.
  • app/genie_alerts.py: Alert testing module for cluster-specific targeting and delivery validation.
  • app/geo.py: Geographic utilities including Haversine distance calculations, bearing computations, and coordinate offsets.
  • app/radius_testing.py: Mile-radius based testing for geographic boundary validation.
  • app/aws_sns.py: AWS SNS integration for endpoint ARN management and push notification testing.
  • app/sqs_alerts.py: AWS SQS consumer for validating message delivery to Android devices.

2. Streamlit-Based Test GUI

Interactive dashboard for non-technical QA testing:

  • Configuration Panel: Device ARN input, coordinate entry, authentication mode selection, AWS credential configuration, and clustering threshold parameters.
  • Device Actions: Register new devices, update locations, refresh device state with real-time status feedback.
  • Clusters View: List and analyze active clusters with detailed information display.
  • Alert Testing: Send alerts through Genie API, test cluster-specific targeting, validate delivery to registered devices.
  • Quick Moves: Preset location buttons, distance-based movement tools, and threshold-crossing test scenarios.

3. Authentication System

  • Multi-Mode Support: Configurable authentication via environment variables supporting none, api_key, and bearer modes.
  • Automatic Switching: Session-based authentication mode selection with proper header injection (x-api-key or Authorization: Bearer).
  • Environment Variables: GENIE_BASE_URL, GENIE_AUTH_MODE, GENIE_API_KEY, GENIE_BEARER_TOKEN, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY.

4. pytest Test Suite

Comprehensive automated test coverage in tests/ directory:

  • test_alert_details.py: Alert content and metadata validation.
  • test_alert_patch.py: Alert update and modification testing.
  • test_alert_summary.py: Summary endpoint and aggregation testing.
  • test_alert_validation.py: Input validation and error handling tests.
  • test_flows.py: End-to-end workflow testing for device registration, location updates, and clustering.
  • test_radius_testing.py: Geographic radius boundary tests.
  • test_sqs_alerts.py: AWS SQS message delivery validation.

5. Geographic Utilities

  • Haversine Distance: Precise distance calculations between GPS coordinates accounting for Earth's curvature.
  • Coordinate Offset: Generate new coordinates at specified distance and bearing from a reference point.
  • Bearing Calculation: Compute heading between two geographic points for movement simulation.
  • Threshold Testing: Automated tests for devices at exact boundary distances and rapid cluster oscillation scenarios.

Implementation Details

  • Base URL: Configurable Genie API endpoint (default: https://geniedev.govigilant.app).
  • Device ARN Format: SNS application endpoint ARNs (APNS_SANDBOX or similar) for push notification targeting.
  • Dual Entrypoints: run.py for Streamlit GUI launch; app/main.py for programmatic/CI execution.
  • Session Management: Streamlit session state for persistent configuration across interactions.
  • Error Handling: Comprehensive exception handling with retry logic and user-friendly error messages.

Results

  • GUI-driven test rig enables non-technical stakeholders to validate clustering behavior without writing code.
  • Automated test suites catch regressions in alert delivery and clustering logic that manual testing frequently misses.
  • Repeatable test workflows with documented configurations for consistent QA across development cycles.
  • pytest integration enables headless execution in CI/CD pipelines for automated regression testing.
  • AWS integration validates end-to-end message delivery through SNS and SQS infrastructure.

Limitations

  • Simulated device movement may not capture all real-world GPS noise and network latency patterns.
  • Testing against live API introduces external dependencies; mock API support would improve offline reliability.
  • Streamlit's stateless architecture limits complex multi-step test workflows within a single session.
  • AWS credentials required for SNS/SQS testing; local-only mode would improve accessibility.

Skills and Technologies Demonstrated

  • Test automation and QA engineering
  • Streamlit dashboard development
  • AWS SNS/SQS integration for push notifications
  • Haversine distance and geographic calculations
  • REST API integration and validation testing
  • pytest framework for automated testing
  • Python application architecture with modular design
  • Environment-based configuration management

Resources