buoy_impersonate 0.3.2

Configure user overrides for integrated Flutter requests. The app and backend must support and authorize impersonation.

buoy_impersonate

Connect test-user search and user-switching behavior to your app.

Requirements

Use a Flutter debug build and a Free or Pro Buoy account key. These packages require Dart 3.9 or later, below 4.0, and Flutter 3.27 or later; your Flutter installation must satisfy both constraints. The Buoy widget does not start its tools in profile or release builds, including with Pro.

Install and register

flutter pub add buoy_impersonate

This example registers the standalone package. In an existing app, keep your screens and providers and apply the registration and builder changes to that app. Complete the tool-specific integration below before testing capture.

import 'package:buoy_impersonate/buoy_impersonate.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (kDebugMode) registerBuoyImpersonate();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => BuoyDevTools(
        licenseKey: const String.fromEnvironment('BUOY_KEY'),
        child: child ?? const SizedBox.shrink(),
      ),
      home: const Scaffold(body: Center(child: Text('Buoy test app'))),
    );
  }
}

Get a key from your Buoy account, then run:

flutter run --dart-define=BUOY_KEY=YOUR_LICENSE_KEY

The standalone setup above avoids an umbrella initialization limitation: mounting the umbrella calls registerBuoyImpersonate() without callbacks, which can clear callbacks registered earlier. If you use the umbrella, apply your configured registration after it mounts and verify search and cache clearing. See the Flutter Quick Start for the umbrella builder.

Connect authentication and HTTP

The tool needs your user-search function and optional cache-clearing callbacks. Configure the standalone registration call before runApp. This fragment uses your existing api, cache, and Dio client; import package:dio/dio.dart in the file that owns the client:

registerBuoyImpersonate(
  onSearchUsers: (query) async => api.searchUsers(query),
  onClearReactQuery: () => cache.clear(),
);

dio.interceptors.add(InterceptorsWrapper(onRequest: (options, handler) {
  options.headers.addAll(BuoyImpersonate.instance.impersonationHeaders);
  handler.next(options);
}));

api.searchUsers must return List<ImpersonateUser>. The callback name onClearReactQuery is part of this API; in Flutter, supply your own cache-clearing operation. Buoy does not infer your state-management reset behavior.

Flutter has no global fetch hook for this feature. Add the headers to each HTTP client you intend to use, and have the backend verify that the caller is authorized to impersonate the selected identity. Account access to Buoy does not grant that backend permission. Review restored impersonation state when restarting a test session.

Check the integration

Switch between two authorized test identities. Check the displayed identity and the headers received by your backend, then end impersonation and verify the original session.

Desktop and MCP

Open Buoy Desktop, sign in, and select the connected device. The default broker port is 42831. The iOS Simulator uses localhost; the Android emulator maps localhost to its host address. For a physical device, set socketUrl: 'http://YOUR_COMPUTER_LAN_IP:42831' on BuoyDevTools and use a network that can reach your computer.

MCP needs separate process account configuration and Pro access. Remote capabilities depend on each tool's adapter. Account validation makes network requests, and device sessions can cross your LAN. See Telemetry for data-flow details.

Full Impersonate guide

License

Proprietary software. © Buoy LLC. See the Terms of Service and pricing.