Skip to content

README.md

Latest commit

 

History

History
284 lines (200 loc) · 6.55 KB

README.md

File metadata and controls

284 lines (200 loc) · 6.55 KB

🚀 Flutter Test Pilot

Version 2.0.0 - A comprehensive Flutter automation testing framework with native Android support, intelligent caching, and parallel execution.

✨ Features

Phase 1 - Core Foundation ✅

  • 🎯 Intelligent CLI - Production-ready command-line interface
  • ⚡ Smart Caching - SQLite-based test result caching (40x faster re-runs)
  • 📱 Device Management - Unified Android & iOS device handling
  • 🔍 Environment Validation - doctor command checks all dependencies

Phase 2 - Native Android Support ✅

  • 🤖 Native Dialog Handling - Auto-dismiss Google Credential Picker, permission dialogs
  • 📋 Permission Management - Pre-grant permissions before tests
  • ⚙️ Device Configuration - Disable animations, clear app data
  • 🔧 UI Automator Integration - Java-based watcher for native dialogs

Phase 3 - Advanced Features ✅

  • 🔄 Retry Handler - Exponential backoff for flaky tests
  • ⚡ Parallel Execution - Run tests across multiple devices simultaneously
  • 📸 Screenshot & Video - Capture on failure, record test sessions
  • 🔍 Test Discovery - Tag-based filtering, glob patterns

📚 Documentation

All documentation has been organized in the doc/ folder:

Quick Links

🚀 Quick Start

Installation

# Add to your Flutter project's pubspec.yaml
dependencies:
  flutter_test_pilot:
    path: ../iltc-services/flutter_test_pilot

Basic Usage

# 1. Check environment
flutter_test_pilot doctor

# 2. Run a simple test
flutter_test_pilot run integration_test/app_test.dart

# 3. Run with native features
flutter_test_pilot run integration_test/app_test.dart \
  --app-id=com.example.myapp \
  --native-watcher \
  --pre-grant-permissions=all \
  --disable-animations

📖 Command Reference

Essential Commands

# Environment check
flutter_test_pilot doctor

# List devices
flutter_test_pilot devices

# Run test
flutter_test_pilot run <test_file>

# Run with full features
flutter_test_pilot run <test_file> \
  --app-id=<package_name> \
  --native-watcher \
  --pre-grant-permissions=all \
  --disable-animations \
  --retry=3 \
  --screenshot \
  --parallel \
  --concurrency=3

Native Features

# Pre-grant permissions
--pre-grant-permissions=none|common|all|custom
--custom-permissions=CAMERA,LOCATION

# Native dialog handling
--native-watcher

# Device configuration
--disable-animations
--clear-app-data

For detailed command documentation, see Documentation Index.

🎯 Key Features

1. Native Dialog Handling

Automatically dismisses native Android dialogs:

  • Google Credential Picker
  • Permission dialogs
  • Location settings
  • System alerts
  • ANR dialogs
flutter_test_pilot run integration_test/login_test.dart \
  --app-id=com.example.myapp \
  --native-watcher

2. Smart Permission Management

Pre-grant permissions to avoid runtime dialogs:

# Grant all permissions
--pre-grant-permissions=all

# Grant common permissions
--pre-grant-permissions=common

# Grant specific permissions
--pre-grant-permissions=custom \
--custom-permissions=CAMERA,RECORD_AUDIO

3. Parallel Execution

Run tests across multiple devices simultaneously:

flutter_test_pilot run integration_test/ \
  --parallel \
  --concurrency=3

Performance: 3x-10x faster test execution!

4. Retry Logic

Automatically retry flaky tests with exponential backoff:

flutter_test_pilot run integration_test/app_test.dart \
  --retry=3

5. Screenshot Capture

Automatically capture screenshots on test failure:

flutter_test_pilot run integration_test/app_test.dart \
  --screenshot

🏗️ Architecture

flutter_test_pilot/
├── lib/
│   ├── src/                    # Internal implementation
│   │   ├── cli/                # CLI commands
│   │   ├── core/               # Core framework (cache, config, models)
│   │   ├── native/             # Native Android support
│   │   ├── executor/           # Test execution
│   │   ├── discovery/          # Test discovery
│   │   └── reporting/          # Screenshots & reports
│   └── flutter_test_pilot.dart # Main export file
│
├── native_assets/
│   └── android/                # Java UI Automator watcher
│       └── src/main/java/com/testpilot/watcher/
│           └── NativeWatcher.java
│
├── doc/                        # 📚 All documentation
└── bin/                        # CLI entry point

📊 Performance Benefits

Feature Before After Improvement
Cached test re-run 120s 3s 40x faster
30 tests sequential 450s 150s (parallel) 3x faster
Flaky test success 60% 95% (retry) +58%
Tests with dialogs ❌ Hangs ✅ Auto-handled Infinite

🛠️ Setup Native Features

1. Build the Native Watcher (One-time)

cd native_assets/android
./build_watcher.sh

This creates build/libs/native_watcher.apk used for dialog handling.

2. Use in Tests

flutter_test_pilot run integration_test/app_test.dart \
  --app-id=YOUR_PACKAGE_NAME \
  --native-watcher \
  --pre-grant-permissions=all

📚 Learn More

Visit the Documentation Index for:

  • Complete feature guides
  • Implementation details
  • Real-world examples
  • Troubleshooting tips
  • API documentation

🐛 Troubleshooting

Quick Fixes

# Environment issues
flutter_test_pilot doctor --verbose

# Clear cache
flutter_test_pilot cache --clear

# Build native watcher
cd native_assets/android && ./build_watcher.sh

# Check devices
adb devices

For detailed troubleshooting, see Real World Usage Guide.

📄 License

Copyright © ILTC Development Team

Built with ❤️ by the ILTC Flutter Team