testerpaykit 0.4.1

Privacy-first Flutter SDK for app testing with pay-by-use testers. Local-first data capture with weekly summaries.

TesterPayKit

A comprehensive Flutter SDK for managing professional testing workflows with built-in bug reporting, crash handling, and session management.

Overview

TesterPayKit transforms your Flutter app into a professional testing environment, enabling testers to efficiently report bugs, track sessions, and provide valuable feedback. The SDK automatically captures device context, user journeys, and crash information to help developers reproduce and fix issues faster.

Features

🐛 Bug Reporting

• Shake-to-report: Shake your device to instantly open the bug report dialog
• Rich categorization: Organize bugs by type, severity, and category
• Auto-context capture: Automatically captures device state, app state, and user journey breadcrumbs
• Reproduction steps: Guide testers to provide detailed reproduction steps
• Screenshot support: Ready for screenshot and screen recording attachments

💥 Crash Handling

• Automatic crash detection: Captures Flutter errors and platform exceptions
• Post-crash reporting: Shows crash report dialog on next app launch
• Full crash context: Includes stack traces, device info, app state, and breadcrumbs
• Battery & network info: Captures battery level, charging state, and network connectivity
• Memory tracking: Basic memory tracking structure (platform-specific implementation required)

📊 Session Management

• Automatic session tracking: Tracks session start, end, duration, and activity
• Session end feedback: Structured feedback collection at session completion
• Session stats: Screen views, taps, and event counts
• Session breadcrumbs: Complete user journey tracking

🎯 Tester Dashboard

• Daily tasks: Show assigned test tasks to testers
• Build information: Display current app version and build details
• Focus areas: Highlight specific features to test
• One-time-per-day: Smart dashboard that shows once daily

🔔 Notifications

• Floating feedback button: Always-accessible button with notification badge
• Unreported items counter: Shows count of unreported crashes and draft bug reports
• Quick actions: Access bug reporting, feedback, dashboard, and session end

🔒 Privacy & Security

• Local-first architecture: All data stored locally in SQLite database
• Device ID rotation: Automatic 30-day device ID rotation for privacy
• GDPR compliant: Built with privacy-first principles
• No tracking without consent: Explicit initialization required

🗄️ Data Management

• SQLite database: Fast, reliable local storage with Drift ORM
• Automatic migrations: Schema versioning and migrations
• Event tracking: Comprehensive event logging system
• Breadcrumb tracking: User action history for context

Installation

Add TesterPayKit to your pubspec.yaml:

dependencies:
  testerpaykit: ^0.1.0

Then run:

flutter pub get

Quick Start

1. Initialize the SDK

In your main.dart:

import 'package:flutter/material.dart';
import 'package:testerpaykit/testerpaykit.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize TesterPayKit
  final sdk = await TesterPayKit.initialize(
    config: TesterPayKitConfig(
      apiBaseUrl: 'https://your-api.com',
      projectId: 'your-project-id',
      testerId: 'tester-id',
      enableLogging: true,
    ),
  );

  runApp(MyApp(sdk: sdk));
}

2. Wrap your app with TesterPayKitWrapper

class MyApp extends StatelessWidget {
  final TesterPayKit sdk;

  const MyApp({required this.sdk, super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: TesterPayKitWrapper(
        sdk: sdk,
        child: YourHomeScreen(),
      ),
    );
  }
}

3. Start using the SDK

The SDK automatically:

• Shows the tester dashboard on first daily launch
• Tracks sessions and user events
• Enables shake-to-report bug functionality
• Detects and reports crashes
• Provides a floating feedback button

Usage Examples

Manual Bug Reporting

// Show bug report dialog programmatically
await sdk.crashHandlerService.showBugReportDialog(context);

Session Management

// Start a session (automatic with TesterPayKitWrapper)
await sdk.sessionManager.startSession();

// End a session with feedback
await sdk.sessionManager.endSession();

Custom Event Tracking

// Track custom events
sdk.eventTracker.trackEvent(
  EventType.custom,
  metadata: {'action': 'button_clicked', 'button_id': 'submit'},
);

Breadcrumb Tracking

// Add breadcrumbs for user journey
sdk.breadcrumbTracker.addBreadcrumb(
  message: 'User navigated to settings',
  category: 'navigation',
  type: BreadcrumbType.navigation,
);

Check for Unreported Crashes

// Show crash report dialog if there are unreported crashes
await sdk.crashHandlerService.checkForUnreportedCrashes(
  context,
  shouldReport: true, // Show dialog
);

Custom Dashboard Data

TesterPayKitWrapper(
  sdk: sdk,
  testTasks: [
    TestTask(
      id: '1',
      title: 'Test login flow',
      description: 'Verify all login scenarios',
      priority: TaskPriority.high,
    ),
  ],
  buildInfo: BuildInfo(
    version: '1.2.0',
    buildNumber: '42',
    environment: 'staging',
  ),
  focusAreas: [
    FocusArea(
      title: 'Payment Flow',
      description: 'Test all payment scenarios',
      priority: 1,
    ),
  ],
  child: YourHomeScreen(),
);

Architecture

Database Schema

TesterPayKit uses Drift (SQLite) for local data storage:

• Events: User interactions, errors, crashes
• Sessions: Testing session tracking
• BugReports: Detailed bug reports with context
• CrashContexts: Crash information with full context
• Breadcrumbs: User journey tracking
• SessionEndFeedbacks: Session completion feedback
• DeviceIdMetadata: Device ID rotation management

Data Flow

User Action → Event Tracker → Local Database → Aggregation → API Submission
                    ↓
            Breadcrumb Tracker
                    ↓
            Crash Handler (if error)

Configuration

TesterPayKitConfig Options

TesterPayKitConfig(
  apiBaseUrl: 'https://api.example.com',  // Required
  projectId: 'project-123',               // Required
  testerId: 'tester-456',                 // Required
  enableLogging: true,                    // Optional, default: false
  logLevel: LogLevel.debug,               // Optional, default: info
  autoSubmitCrashes: false,               // Optional, default: false
  maxBreadcrumbs: 100,                    // Optional, default: 100
)

Platform Support

• ✅ Android
• ✅ iOS
• ✅ Linux
• ✅ macOS
• ✅ Windows

Dependencies

Key dependencies:

• drift - Local database
• battery_plus - Battery level detection
• connectivity_plus - Network status
• device_info_plus - Device information
• shake - Shake gesture detection
• shared_preferences - Persistent key-value storage

Requirements

• Flutter SDK: >=3.5.0
• Dart SDK: >=3.5.0

Documentation

• Bug Reporting Guide
• Crash Handling Guide
• API Documentation

Roadmap

Phase 1: MVP Bug Reporting ✅ (Current)

• ✅ Bug report dialog with rich categorization
• ✅ Crash detection and reporting
• ✅ Session end feedback
• ✅ Shake-to-report
• ✅ Device ID rotation
• ✅ Notification badge

Phase 2: Rich Feedback (Planned)

• 📸 Screenshot capture and annotation
• 🎥 Screen recording
• 🗣️ Voice notes
• 📊 Network request capture
• 🎨 Visual regression detection

Phase 3: Gamification (Planned)

• 🎮 Points and achievements
• 🏆 Leaderboards
• 📈 Tester analytics dashboard
• 💰 Earnings tracking

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentation

Acknowledgments

Built with ❤️ for the testing community.