Flutter机器人控制插件flutter_robot的使用

Flutter机器人控制插件flutter_robot的使用

简介

flutter_robot 是一个用于创建页面测试的插件，通过模拟多设备屏幕大小、iOS主按钮、状态栏和键盘打开等场景，验证控制器（如Cubit/Bloc/MobX等）与视图之间的正确交互。

安装

首先，在项目的 pubspec.yaml 文件中添加 flutter_robot 作为开发依赖项：

$ dart pub add dev:flutter_robot

创建第一个机器人测试

第一步 - 创建机器人

在项目中创建两个文件：{page_name}_robot.dart 和 {page_name}_test.dart。我们以 my_feature_page_robot.dart 和 my_feature_page_test.dart 为例。

my_feature_page_robot.dart

class MyFeaturePageRobot extends Robot {
  MyFeaturePageRobot({
    required super.tester,
  });

  @override
  Widget build() {
    // 返回要测试的页面或小部件
    return const MyFeaturePage();
  }

  Future<void> assertScreen() {
    // 捕获当前屏幕快照
    return takeSnapshot('MyFeaturePage_screen');
  }

  // 创建其他方法来与 'WidgetTester' API 交互，如 tap、enterText 等。
  // 或者使用 RobotElement 查找小部件并与其交互。
}

第二步 - 创建测试

my_feature_page_test.dart

import 'package:flutter_robot/flutter_robot.dart';
import 'package:flutter_test/flutter_test.dart';

import 'my_feature_page_robot.dart';

void main() {
  // 设置机器人
  setUpRobot(
    (tester) => MyFeaturePageRobot(tester: tester),
  );

  // 运行测试
  testRobot<MyFeaturePageRobot>(
    'Should show page correctly',
    (robot) async {
      await robot.assertScreen();
    },
  );
}

创建黄金文件

运行以下命令更新黄金文件：

$ flutter test --update-goldens

如果一切正常，测试将通过并生成名为 golden_files 的文件夹，并在其中创建 MyFeaturePage_screen.png 文件。

使用场景

第一步 - 创建场景

在 my_feature_page_scenarios.dart 中定义场景：

abstract class MyFeaturePageScenarios extends RobotScenario {
  @override
  FutureOr<void> injectDependencies() {}

  @override
  FutureOr<void> mockScenario() {}
}

第二步 - 实现基础机器人文件

my_feature_page_robot.dart

class MyFeaturePageRobot extends Robot<MyFeaturePageScenarios> {
  MyFeaturePageRobot({
    required super.tester,
    required super.scenario,
  });

  @override
  Widget build() {
    return const MyFeaturePage();
  }

  Future<void> assertSuccessScreenGolden() {
    // 捕获成功场景的快照
    return takeSnapshot('MyFeaturePage_success');
  }
}

第三步 - 创建测试

my_feature_page_test.dart

import 'package:flutter_test/flutter_test.dart';

import 'my_feature_page_robot.dart';
import 'my_feature_page_scenarios.dart';

void main() {
  // 设置机器人
  setUpRobot(
    (tester) => MyFeaturePageRobot(
      tester: tester,
    ),
  );

  // 运行测试
  testRobot<MyFeaturePageRobot>(
    'Should show the success case correctly',
    (robot) async {
      await robot.assertSuccessScreenGolden();
    },
    scenario: MyFeaturePageSuccess(), // 定义成功的场景
  );
}

在多设备上运行测试

为了在多设备上运行测试，可以传递 devices 参数给 testRobot 方法：

void main() {
  // 设置机器人
  setUpRobot(
    (tester) => MyFeaturePageRobot(
      tester: tester,
    ),
  );

  // 运行测试
  testRobot<MyFeaturePageRobot>(
    'Should run in all devices',
    (robot) async {
      await robot.assertScreen();
    },
    devices: [
      RobotDevice.small(),
      RobotDevice.medium(),
      RobotDevice.large(),
      RobotDevice(
        name: 'custom',
        sizeScreen: const Size(800, 800),
        withStatusBar: true,
        withKeyboard: true,
        withIOSHomeButton: true,
      ),
    ],
  );
}

使用 RobotElement

RobotElement 可帮助你查找和与小部件树中的特定元素进行交互。

my_feature_page_robot.dart

class MyFeaturePageRobot extends Robot {
  MyFeaturePageRobot({
    required super.tester,
  });

  @override
  Widget build() {
    return const MyFeaturePage();
  }

  // 通过键获取特定元素
  RobotElement get submitButton => RobotElement.byKey(Key('submit_button'), tester);

  // 通过类型获取元素
  RobotElement get textField => RobotElement.byType(TextField, tester);

  // 通过文本获取元素
  RobotElement get welcomeText => RobotElement.byText('Welcome!', tester);

  // 通过图标获取元素
  RobotElement get settingsIcon => RobotElement.byIcon(Icons.settings, tester);
}

my_feature_page_test.dart

void main() {
  // 设置机器人
  setUpRobot(
    (tester) => MyFeaturePageRobot(tester: tester),
  );

  // 运行测试
  testRobot<MyFeaturePageRobot>(
    'Should interact with the elements',
    (robot) async {
      await robot.submitButton.scrollTo();
      await robot.submitButton.tap();
      await robot.welcomeText.assertIsVisible();
      await robot.settingsIcon.longPress();
      await robot.textField.enterText('Test input');
    },
  );
}

加载字体

要加载字体以在黄金文件中显示文本和图标，可以使用 RobotFontLoaderManager。

flutter_test_config.dart

import 'dart:async';

import 'package:flutter_robot/flutter_robot.dart';

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  RobotFontLoaderManager().add(MyCustomIconFontLoader());
  return testMain();
}

或者覆盖 Robot 类中的 fontLoaders 方法：

import 'dart:async';

import 'package:flutter_robot/flutter_robot.dart';

class MyRobot extends Robot {
  List<RobotFontLoader> get fontLoaders => [
    MyCustomIconFontLoader(),
  ];
}

加载资源

Robot 会尝试加载小部件树中的所有 ImageProvider。如果需要手动加载资源，可以调用 loadAsyncImageProvider。

黄金文件差异阈值

为了处理在不同操作系统上的差异，可以设置 threshold 来避免小差异导致测试失败。

flutter_test_config.dart

import 'dart:async';

import 'package:flutter_robot/flutter_robot.dart';

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  RobotFileComparator.thresholdDefault = 0.05; // 5%
  return testMain();
}

也可以为特定的 Robot 设置 threshold：

class ExamplePageRobot extends Robot {
  ExamplePageRobot({
    required super.tester,
    required super.scenario,
  }) : super(goldenThreshold: 0.05);

  ...
}