When to Choose Flutter Cockpit

Flutter Cockpit is a Testing and Quality package that provides a semantic automation bridge for Cockpit E2E tests. It shines when you need a ready‑made observation, capture, and recording layer without writing every utility from scratch. Consider using it if:

  • You already run Cockpit‑based end‑to‑end tests for your mobile or web builds.
  • You want a single entry point for test‑related side effects (screenshots, event logs, performance markers).
  • You prefer to keep test helpers isolated behind a clear architectural boundary.

Tip: Evaluate the package against your CI pipeline early. If the API changes across versions, pin a stable version in pubspec.yaml.

Installation

Add the package with the standard Flutter command:

Code
flutter pub add flutter_cockpit

After the command finishes, run flutter pub get to fetch the dependency.

Basic Setup

Because the package is intended for testing utilities, the recommended practice is to wrap all calls inside a dedicated service. This keeps UI widgets free from direct package imports and makes future replacement straightforward.

Creating a Cockpit Service

Dart / Flutter
import 'package:flutter_cockpit/flutter_cockpit.dart';

/// A thin wrapper around the flutter_cockpit API.
class CockpitService {
  /// Initializes the Cockpit bridge. Call this once, typically in
  /// initState of a top‑level widget or a DI container.
  Future init() async {
    // The actual method name may differ – check the package README.
    await FlutterCockpit.initialize();
  }

  /// Records a custom label or snapshot. The exact payload depends on
  /// the Cockpit configuration you use.
  void capture(String label) {
    FlutterCockpit.record(label);
  }

  /// Shuts down the bridge and releases native resources.
  Future dispose() async {
    await FlutterCockpit.shutdown();
  }
}

Tip: Keep the service stateless; let the underlying package manage its own state.

Using the Service in a Widget

Dart / Flutter
import 'package:flutter/material.dart';
import 'cockpit_service.dart';

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key}) : super(key: key);

  @override
  State createState() => _MyHomePageState();
}

class _MyHomePageState extends State {
  final CockpitService _cockpit = CockpitService();

  @override
  void initState() {
    super.initState();
    _cockpit.init();
  }

  @override
  void dispose() {
    _cockpit.dispose();
    super.dispose();
  }

  void _onButtonPressed() {
    // Capture a custom event that Cockpit can later assert against.
    _cockpit.capture('button_pressed');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Flutter Cockpit Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: _onButtonPressed,
          child: const Text('Capture Event'),
        ),
      ),
    );
  }
}

Mistakes to Avoid

  • Spreading package calls throughout UI code. This creates a hard‑to‑replace dependency and makes testing harder.
  • Skipping version pinning. The package may introduce breaking changes; use a caret or exact version range in pubspec.yaml.
  • Running Cockpit APIs in production builds. Guard calls with kDebugMode or a custom feature flag.
  • Ignoring platform compatibility. Verify that the underlying native bridge works on iOS, Android, and web before shipping.

Further Reading & Resources

  • Package page on pub.dev: flutter_cockpit
  • Official documentation and API reference (linked from the pub.dev page).
  • Flutter testing best practices – see the Flutter website for broader context.

Frequently Asked Questions

Do I need to import flutter_cockpit in every file that uses it?

No. Import the package only in a dedicated service or helper class and expose high‑level methods to the rest of your code. This keeps the dependency isolated and easier to replace.

Can flutter_cockpit be used in production builds?

The package is primarily designed for testing and quality workflows. If you need to keep it out of production, guard calls with <code>kDebugMode</code> or a runtime flag.

What should I do if the API changes after a package upgrade?

Pin a known‑good version in <code>pubspec.yaml</code>, review the changelog on pub.dev, and run your integration tests after any upgrade to catch breaking changes early.

Is flutter_cockpit compatible with Flutter web?

Compatibility depends on the native bridge used by the package. Check the package's pub.dev page and documentation for explicit web support before using it in a web project.