flutter_crash_now

A lightweight Flutter plugin to simulate app crashes during development and testing, or forcibly terminate the app when tampering is detected.

✨ Features

• 🚀 Cross-platform: Support for iOS, Android, Windows, macOS, and Linux
• ⚡ FFI Implementation: Built with Dart FFI for excellent performance
• 🎯 Simple to Use: Trigger crashes with just one line of code
• 🔒 Reliable: Uses system-level signal mechanism to ensure complete termination
• 📦 Zero Dependencies: No additional third-party dependencies required

📋 Use Cases

• ✅ Test crash log collection systems (Firebase Crashlytics, Sentry, etc.)
• ✅ Verify app recovery mechanisms after crashes
• ✅ Security protection when app tampering is detected
• ✅ Error handling workflow testing during development
• ✅ Stress testing and stability testing

🚀 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_crash_now: ^1.0.0

Then install it:

flutter pub get

Or install from command line:

flutter pub add flutter_crash_now

📖 Usage

Basic Usage

import 'package:flutter_crash_now/flutter_crash_now.dart';

// Get plugin version
print(FlutterCrashNow.version); // Output: 1.0.0

// Trigger app crash
FlutterCrashNow.crash();

Complete Example

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Crash Now Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Crash Test'),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // Show confirmation dialog
            showDialog(
              context: context,
              builder: (context) => AlertDialog(
                title: const Text('Warning'),
                content: const Text('Are you sure you want to trigger app crash?'),
                actions: [
                  TextButton(
                    onPressed: () => Navigator.pop(context),
                    child: const Text('Cancel'),
                  ),
                  TextButton(
                    onPressed: () {
                      Navigator.pop(context);
                      // Trigger crash
                      FlutterCrashNow.crash();
                    },
                    child: const Text('Confirm'),
                  ),
                ],
              ),
            );
          },
          child: const Text('Trigger Crash'),
        ),
      ),
    );
  }
}

🔧 Technical Implementation

This plugin uses FFI (Foreign Function Interface) technology to trigger app crashes by calling system-level signal mechanisms.

Core code snippet:

signal(SIGABRT, SIG_IGN);  // Ignore signal handlers
abort();                    // Force crash

How it works:

1. signal(SIGABRT, SIG_IGN) - Removes any custom signal handlers that might catch the crash
2. abort() - Sends SIGABRT signal and terminates the process immediately

This implementation ensures:

• The app terminates immediately without being caught
• The system generates crash reports
• Crash logging tools can properly capture crash information
• Cannot be intercepted by try-catch or signal handlers

⚠️ Important Notes

1. For Development & Testing Only: Do not use this plugin in production unless you have specific security requirements (e.g., anti-tampering protection)
2. Cannot Be Caught: Crashes triggered this way cannot be caught by try-catch
3. Data Loss: The crash immediately terminates the app - ensure important data is saved first
4. User Experience: Using in production will negatively impact user experience - use with caution

🔒 Security Use Cases

In security-sensitive applications, you can use this plugin to forcibly terminate the app when certain conditions are detected:

// App tampering detected
if (isAppTampered()) {
  FlutterCrashNow.crash();
}

// Root/Jailbreak detected (use with other detection plugins)
if (isDeviceRooted()) {
  FlutterCrashNow.crash();
}

// Debugger attached detected
if (isDebuggerAttached()) {
  FlutterCrashNow.crash();
}

🧪 Testing Crash Reporting

With Firebase Crashlytics

import 'package:firebase_crashlytics/firebase_crashlytics.dart';
import 'package:flutter_crash_now/flutter_crash_now.dart';

void testCrashReporting() {
  // Log custom message
  FirebaseCrashlytics.instance.log('Preparing to trigger test crash');
  
  // Set custom key-value
  FirebaseCrashlytics.instance.setCustomKey('test_crash', true);
  
  // Trigger crash
  FlutterCrashNow.crash();
}

With Sentry

import 'package:sentry_flutter/sentry_flutter.dart';
import 'package:flutter_crash_now/flutter_crash_now.dart';

void testSentryCrash() {
  // Add breadcrumb
  Sentry.addBreadcrumb(Breadcrumb(
    message: 'User triggered test crash',
    level: SentryLevel.info,
  ));
  
  // Trigger crash
  FlutterCrashNow.crash();
}

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

Meterwhite

🔗 Links

• Pub.dev
• GitHub
• Issue Tracker

❓ FAQ

Q: Why do I need this plugin?

A: During development, you need to test whether crash logging systems are working correctly. This plugin simulates real crash scenarios.

Q: Is this plugin safe?

A: Yes, the plugin uses standard system signal mechanisms and won't harm your system. However, only use it in development and testing environments.

Q: Can I use it in production?

A: Not recommended for casual use in production. Only use in specific security scenarios (e.g., forcing termination when tampering is detected), as it will severely impact user experience.

Q: Can the crash be caught?

A: No. This plugin triggers system-level crashes that cannot be caught by Dart's try-catch mechanism.

Q: Which platforms are supported?

A: All major platforms: iOS, Android, Windows, macOS, and Linux.

---

⚠️ Remember: This is a powerful tool - use it responsibly! Only trigger crashes intentionally during testing or when detecting security threats.