fast_flutter_driver_tool 3.0.0

Toolkit for running rapidly flutter driver tests on desktop.

Fast Flutter Driver

Plugin	Pub
Command Line Tool
UI Helper

Deprecation Warning

Flutter Driver tests are being deprecated in favor of new Integration Tests. I will continue to support this package as long it's feasible but it is recommended to start using Integration Tests.

You can read more Pros and Cons here.

Toolkit for running rapidly flutter driver tests on desktop/mobile.

This package simplifies the creation of Flutter Driver tests that can be run in bulk without restarting or rebuilding the application. An example of how the toolkit works can be found in this article.

The reasoning for Desktop tests

The desktop builds are almost identical to Android/iOS builds in regard to the UI. Running tests on a simulator/emulator are painful. This can be even worse on your CI.

Your CI is usually a dockerized Linux machine - running Linux flutter driver tests against Linux Flutter application is both fast and reliable. This tool allows you to run your flutter driver tests much faster and more reliably than a build for a simulator/emulator.

The application flows that require Android/iOS plugins should still be run on a Simulator/Emulator or a real device.

Running also on Android/iOS

While running tests against Desktop will find the majority of bugs, it is recommended to run sometimes against an actual devices. There are bugs in Dart (like implementing your generics in an invalid way) that can cause a native crash on a mobile device and work properly on the desktop.It's prudent to run fastdriver tests before every release on a mobile device.

Example

You can build and execute the example that works on any desktop system and Docker as well.

Usage

• Add dev_dependency to your pubspec.yaml

dev_dependencies:
  fast_flutter_driver: ^2.0.0

• Create configuration class test_driver/generic/test_configuration.dart

import 'package:fast_flutter_driver/tool.dart';
import 'package:meta/meta.dart';

class TestConfiguration implements BaseConfiguration {
  const TestConfiguration({
    required this.resolution,
    this.platform,
  });

  factory TestConfiguration.fromJson(Map<String, dynamic> json) {
    return TestConfiguration(
      resolution: Resolution.fromJson(json['resolution']),
      platform: TestPlatformEx.fromString(json['platform']),
    );
  }
  @override
  final TestPlatform? platform;
  @override
  final Resolution resolution;
  
  @override
  Map<String, dynamic> toJson() {
    final p = platform;
    return <String, dynamic>{
      'resolution': resolution,
      if (p != null) 'platform': p.asString(),
    };
  }
}

• Create dart file test_driver/generic/generic.dart with content and MyApplication as your main (root) application widget.

import 'dart:convert';

import 'package:fast_flutter_driver/driver.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/scheduler.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_driver/driver_extension.dart';

import 'test_configuration.dart';

void main() {
  timeDilation = 0.1;
  enableFlutterDriverExtension(
    handler: (playload) async {
      await configureTest(
        TestConfiguration.fromJson(json.decode(playload ?? '{}')),
      );
      return '';
    },
  );

  runApp(
    RestartWidget<TestConfiguration>(
      builder: (_, config) => MyApplication(),
    ),
  );
}

• Create a test, eg test_driver/main_test.dart

import 'dart:convert';

import 'package:fast_flutter_driver/tool.dart';
import 'package:flutter_driver/flutter_driver.dart';
import 'package:test/test.dart';

import 'generic/test_configuration.dart';

void main(List<String> args) {
  late FlutterDriver driver;
  final properties = TestProperties(args);

  setUpAll(() async {
    driver = await FlutterDriver.connect(dartVmServiceUrl: properties.vmUrl);
  });

  tearDownAll(() async {
    await driver.close();
  });

  Future<void> restart() {
    return driver.requestData(
      json.encode(
        TestConfiguration(
          resolution: properties.resolution,
          platform: properties.platform,
        ),
      ),
    );
  }

  test('main application', () async {
    await restart();

    await driver.waitFor(find.byType('MyApplication'));
  });
}

• Install fast_flutter_driver script:

pub global activate fast_flutter_driver_tool

• Run:

fastdriver --dart-args "--no-sound-null-safety" --flutter-args "--no-sound-null-safety"

All done!

What's next

This was the simplest setup of tests, next you would like to pass different application configuration so every time you run tests, they could be run with a different configuration (eg different page). To do that you need to add more properties to TestConfiguration.

A full example of how to do that can be found in the example folder.

Null Safety

The package supports building project that are migrated to null safety but until flutter driver is migrated to null safety, we need to pass the above flags to the command line tool.