Flutter Testing

全面的 Flutter 测试指导（单元/集成/Widget 测试）

Security Scan

This is an instruction-only Flutter testing guide that only requires the flutter CLI and requests no credentials or installs; its declared requirements match its documented behavior.

Purpose & Capability

Name and description match the content: comprehensive Flutter testing guidance. The only required binary is flutter, which is appropriate and proportionate for this skill.

Instruction Scope

SKILL.md and reference docs contain test examples and commands (e.g., flutter test, CI config). Instructions do not ask the agent to read unrelated files, access secrets, call external endpoints, or exfiltrate data.

Install Mechanism

No install spec and no code files to execute. The skill is instruction-only (documentation), so nothing is written to disk or downloaded during install.

Credentials

No environment variables, credentials, or config paths are requested. Requiring only the flutter binary is proportional to the documented functionality.

Persistence & Privilege

always is false and model invocation is allowed (platform default). The skill does not request persistent privileges or attempt to modify other skills or system settings.

Assessment

This skill is an offline, documentation-style guide for Flutter tests and appears consistent with its purpose. Before installing: (1) confirm you have Flutter on PATH; (2) if you care about provenance, verify the README's referenced GitHub/original source (the package lists an original author and repo) since the skill's Source field is 'unknown'; (3) because it’s able to be invoked autonomously by default, be mindful about giving any skill network/file/system access in other skills—this particular skill does not request such access. If you want absolute assurance, open the referenced GitHub repo and compare contents before use.

Overview

This skill provides comprehensive guidance for testing Flutter applications across all test types. Flutter testing falls into three categories:

• Unit tests - Test individual functions, methods, or classes in isolation
• Widget tests (component tests) - Test single widgets and verify UI appearance and behavior
• Integration tests - Test complete apps or large parts to verify end-to-end functionality

A well-tested Flutter app has many unit and widget tests for code coverage, plus enough integration tests to cover important use cases.

Test Type Trade-offs

Tradeoff	Unit	Widget	Integration
Confidence	Low	Higher	Highest
Maintenance cost	Low	Higher	Highest
Dependencies	Few	More	Most
Execution speed	Quick	Quick	Slow

Build Modes for Testing

Flutter supports three build modes with different implications for testing:

• Debug mode - Use during development with hot reload. Assertions enabled, debugging enabled, but performance is janky
• Profile mode - Use for performance analysis. Similar to release mode but with some debugging features enabled
• Release mode - Use for deployment. Assertions disabled, optimized for speed and size

Quick Start

Unit Tests

Unit tests test a single function, method, or class. Mock external dependencies and avoid disk I/O or UI rendering.

import 'package:test/test.dart';
import 'package:my_app/counter.dart';

void main() {
  test('Counter value should be incremented', () {
    final counter = Counter();
    counter.increment();
    expect(counter.value, 1);
  });
}

Run with: flutter test

Widget Tests

Widget tests test single widgets to verify UI appearance and interaction.

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('MyWidget has a title and message', (tester) async {
    await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
    
    final titleFinder = find.text('T');
    final messageFinder = find.text('M');
    
    expect(titleFinder, findsOneWidget);
    expect(messageFinder, findsOneWidget);
  });
}

Integration Tests

Integration tests test complete apps on real devices or emulators.

import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:my_app/main.dart';

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
  
  testWidgets('tap button, verify counter', (tester) async {
    await tester.pumpWidget(const MyApp());
    expect(find.text('0'), findsOneWidget);
    
    await tester.tap(find.byKey(const ValueKey('increment')));
    await tester.pumpAndSettle();
    
    expect(find.text('1'), findsOneWidget);
  });
}

Run with: flutter test integration_test/

Testing Workflow Decision Tree

1. What are you testing?

   • Single function/class → Unit Tests
   • Single widget/component → Widget Tests
   • Complete user flow → Integration Tests

2. Does it depend on plugins/native code?

   • Yes → See Plugins in Tests or Testing Plugins

3. Need to mock dependencies?

   • Yes → See Mocking Guide (references/mocking.md)

4. Encountering errors?

   • See Common Testing Errors (references/common-errors.md)

Unit Tests

Unit tests verify the correctness of a unit of logic under various conditions.

When to Use Unit Tests

• Testing business logic functions
• Validating data transformations
• Testing state management logic
• Mocking external services/API calls

Key Concepts

• Use package:test/test.dart
• Mock dependencies using Mockito or similar
• Avoid file I/O or UI rendering
• Fast execution, high maintainability

Advanced Unit Testing

For mocking dependencies, plugin interactions, and complex scenarios, see Unit Testing Reference.

Widget Tests

Widget tests verify widget UI appearance and behavior in a test environment.

When to Use Widget Tests

• Testing widget rendering
• Verifying user interactions (taps, drags, scrolling)
• Testing different orientations
• Validating widget state changes

Widget Testing Patterns

Finding Widgets

// By text
final titleFinder = find.text('Title');

// By widget type
final buttonFinder = find.byType(ElevatedButton);

// By key
final fabFinder = find.byKey(const ValueKey('increment'));

// By widget instance
final myWidgetFinder = find.byWidget(myWidgetInstance);

User Interactions

// Tap
await tester.tap(buttonFinder);

// Drag
await tester.drag(listFinder, const Offset(0, -300));

// Enter text
await tester.enterText(fieldFinder, 'Hello World');

// Scroll
await tester.fling(listFinder, const Offset(0, -500), 10000);
await tester.pumpAndSettle();

Testing Different Orientations

testWidgets('widget in landscape mode', (tester) async {
  // Set to landscape
  await tester.binding.setSurfaceSize(const Size(800, 400));
  await tester.pumpWidget(const MyApp());
  
  // Verify landscape behavior
  expect(find.byType(MyWidget), findsOneWidget);
  
  // Reset to portrait
  addTearDown(tester.binding.setSurfaceSize(null));
});

Advanced Widget Testing

For scrolling, complex interactions, and performance testing, see Widget Testing Reference.

Integration Tests

Integration tests test complete apps or large parts on real devices or emulators.

When to Use Integration Tests

• Testing complete user flows
• Verifying multiple screens/pages
• Testing navigation flows
• Performance profiling

Integration Test Structure

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
  
  group('end-to-end test', () {
    testWidgets('complete user flow', (tester) async {
      await tester.pumpWidget(const MyApp());
      
      // Step 1: Navigate to screen
      await tester.tap(find.text('Login'));
      await tester.pumpAndSettle();
      
      // Step 2: Enter credentials
      await tester.enterText(find.byKey(const Key('username')), 'user');
      await tester.enterText(find.byKey(const Key('password')), 'pass');
      
      // Step 3: Submit
      await tester.tap(find.text('Submit'));
      await tester.pumpAndSettle();
      
      // Verify result
      expect(find.text('Welcome'), findsOneWidget);
    });
  });
}

Performance Testing

testWidgets('scrolling performance', (tester) async {
  await tester.pumpWidget(const MyApp());
  
  final listFinder = find.byType(ListView);
  
  // Measure performance
  final timeline = await tester.trace(() async {
    await tester.fling(listFinder, const Offset(0, -500), 10000);
    await tester.pumpAndSettle();
  });
  
  // Analyze timeline data
  expect(timeline.frames.length, greaterThan(10));
});

Advanced Integration Testing

For performance profiling, CI integration, and complex scenarios, see Integration Testing Reference.

Plugins in Tests

When testing code that uses plugins, special handling is required to avoid crashes.

Testing App Code with Plugins

If your Flutter app uses plugins, you need to mock the platform channel calls in unit/widget tests.

import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  TestWidgetsFlutterBinding.ensureInitialized();
  
  setUp(() {
    // Mock platform channel
    TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
        .setMockMethodCallHandler(
      const MethodChannel('your.plugin.channel'),
      (MethodCall methodCall) async {
        if (methodCall.method == 'getPlatformVersion') {
          return 'Android 12';
        }
        return null;
      },
    );
  });
  
  tearDown(() {
    TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
        .setMockMethodCallHandler(
      const MethodChannel('your.plugin.channel'),
      null,
    );
  });
}

Testing Plugins

For comprehensive guidance on testing Flutter plugins (including native code), see Plugin Testing Reference.

Common Testing Errors

'A RenderFlex overflowed...'

Yellow and black stripes indicate overflow. Usually caused by unconstrained children in Row/Column.

Solution: Wrap the overflowing widget in Expanded or Flexible.

// Problem
Row(
  children: [
    Icon(Icons.message),
    Column(children: [Text('Very long text...')]), // Overflow!
  ],
)

// Solution
Row(
  children: [
    Icon(Icons.message),
    Expanded(child: Column(children: [Text('Very long text...')])),
  ],
)

'Vertical viewport was given unbounded height'

Occurs when ListView (or other scrollable) is inside Column without height constraints.

Solution: Wrap in Expanded or use shrinkWrap: true.

// Problem
Column(
  children: [
    Text('Header'),
    ListView(children: [...]), // Error!
  ],
)

// Solution
Column(
  children: [
    Text('Header'),
    Expanded(child: ListView(children: [...])),  ],
)

'setState called during build'

Never call setState during build method.

Solution: Use Navigator API or defer to post-build callback.

For more errors and solutions, see Common Errors Reference.

Testing Best Practices

1. Test Pyramid - More unit/widget tests, fewer integration tests
2. Descriptive Test Names - Names should clearly describe what and why
3. Arrange-Act-Assert - Structure tests with clear sections
4. Avoid Test Interdependence - Each test should be independent
5. Mock External Dependencies - Keep tests fast and reliable
6. Run Tests in CI - Automate testing on every push

Running Tests

Run All Tests

flutter test

Run Specific Test File

flutter test test/widget_test.dart

Run Integration Tests

flutter test integration_test/

Run with Coverage

flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

Run Tests on Different Platforms

# Android
flutter test --platform android

# iOS
flutter test --platform ios

# Web
flutter test --platform chrome

Debugging Tests

Debug a Test

flutter test --no-sound-null-safety test/my_test.dart

Verbose Output

flutter test --verbose

Run Specific Test

flutter test --name "Counter value should be incremented"

Resources

Reference Files

• Unit Testing Guide - In-depth unit testing patterns and mocking strategies
• Widget Testing Guide - Widget finding, interactions, and advanced scenarios
• Integration Testing Guide - End-to-end testing and performance profiling
• Mocking Guide - Mocking dependencies and plugin interactions
• Common Errors - Solutions for frequent testing errors
• Plugin Testing - Testing Flutter plugins with native code

External Resources

• Flutter Testing Documentation
• flutter_test package
• Mockito package
• Integration Test package