Bug reporting for Flutter app testing

What you need

The Flutter SDK is the flawsnap package on pub.dev (version 0.4.0). The steps below follow the Flutter docs. For the web side of the same product, the website widget reports to the same project.

It supports iOS and Android only. There is no Flutter web or desktop support. If your Flutter app also ships to the web, use the website widget there.

The problem: mobile testers lose context the moment they switch apps

A tester running a build on an Android phone sees the order history screen show yesterday's orders twice. To report it they take a screenshot, switch to a chat app, type a note, and forget the build number. The developer doesn't know the device, the OS version, whether dark mode was on, or which request returned the duplicates. On mobile, every app switch loses detail.

How to set it up

1. 1

   Turn on mobile intake

   In the project's Security settings, turn on Accept reports from mobile apps and copy the pk_ key. Apps send no browser origin, so this switch is what lets them in.

2. 2

   Add the package

   Run flutter pub add flawsnap (or add flawsnap: ^0.4.0 to pubspec.yaml). It needs Dart 3.13 and Flutter 3.47 or newer. Android release builds also need the INTERNET permission in the manifest.

3. 3

   Initialise and wrap the app

   Call Flawsnap.init before runApp, and wrap your root widget, as in the example below.

4. 4

   Report the current screen

   Add Flawsnap.navigatorObserver to navigatorObservers. GoRouter and auto_route are covered; for anything else, name a screen with Flawsnap.screen('Settings').

5. 5

   Route requests through the SDK client

   Use Flawsnap.httpClient() (or wrap your own package:http client) so the last 100 requests are attached. Dio and other HTTP clients aren't seen yet. Bodies are never recorded.

import 'package:flawsnap/flawsnap.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Flawsnap.init(
    apiUrl: 'https://backend.flawsnap.com/api/v1',
    projectKey: 'pk_...',
    insights: true, // optional: journeys and API timing on Pro
  );
  runApp(Flawsnap.wrap(const MyApp()));
}

Shake for testers, a button for everyone else

By default a report opens on a shake or from a floating button. Shake needs a physical device, so on emulators testers use the button. Admins can hide the button or set its position and colour from the portal, and your own code can open the reporter with Flawsnap.show(), for example from a hidden menu in internal builds.

With team sign-in on, testers call Flawsnap.signIn(), approve the device on a portal page, and their name goes on every report for 30 days.

What a Flutter report contains

• A screenshot marked up with box and draw, in five colours. There is no arrow, text or blur tool in the Flutter SDK, so ask testers to describe sensitive areas rather than rely on blur.
• Title, description, priority and category, as on the web.
• Device model, OS and version, app name, version and build, screen size, pixel ratio, locale, and light or dark mode.
• The current screen name.
• The last 100 log lines: Flutter errors, uncaught exceptions, debugPrint output and anything you send with Flawsnap.log.
• The last 100 requests made through Flawsnap.httpClient().

There is no screen recording in the Flutter SDK, and native iOS or Android crashes are not captured.

Organising app and web reports

If the app and the website are one product, you can keep them in one project: list the web domains and turn on mobile intake, and reports from both land on one board. The reports list filters by platform (Web, Android, iOS), so a tester can see only app reports. If the app has its own team, give it its own project and restrict that team's members to it.

Pitfalls

• Testing shake on an emulator. It won't trigger; use the button.
• Using Dio. Requests made with Dio won't appear in reports yet. Either route the calls you care about through Flawsnap.httpClient() or log failures with Flawsnap.log.
• Forgetting the build number in the title. It is already attached; testers don't need to type it.

Questions

Where do I get the Flutter SDK?

From pub.dev: flutter pub add flawsnap. The website widget and the portal work alongside it, so web and app testing can share one board.

Does it work with Flutter web?

No. The SDK supports iOS and Android only. For a Flutter web build, install the website widget on the page that hosts the app.

Is the Flutter SDK included in Starter?

Yes. The SDK is included on both Starter and Pro. Insights from the app, such as screens and API timing, needs Pro.

Related

• In-app bug reporting for Flutter apps
• Install Flawsnap in a Flutter app
• Flutter SDK docs
• Device and browser details, filled in for you
• Bug reporting for QA testing