Optimizing Flutter Apps for Automation

This document provides a guide on how to use Finalrun to test your Flutter applications. A key benefit of the approach detailed here is that by making your app testable, you also significantly improve its accessibility for all users.

Overview

Finalrun offers support for testing Flutter applications. It can be used to write and execute tests for both pure-Flutter and hybrid applications. Finalrun is compatible with Flutter mobile (iOS and Android) and Flutter Web applications.

How it Works: Testing and Accessibility Hand-in-Hand

Finalrun interacts with your Flutter application by leveraging its accessibility and semantics system. This is the same system used by assistive technologies like screen readers (e.g., VoiceOver on iOS and TalkBack on Android).

This direct link means that when you make your app testable with Finalrun, you are also making it more accessible. Clear labels for tests are also clear labels for screen readers.

Identifying Widgets

To interact with a widget, Finalrun first needs to find it on the screen. There are several ways to identify a widget, each with implications for both testing and accessibility.

1. By Text

The simplest method is to use the visible text on a widget. This is suitable for widgets like Text and ElevatedButton.

Example Prompt:

Tap on Sign In

2. By Semantic Label

For widgets that do not have visible text (e.g., an IconButton with just an icon), you must add a semanticLabel. This is a critical practice for both testing and accessibility.

This label is what a screen reader will announce to users, allowing them to understand the function of the control.

Flutter Code:

IconButton(
  icon: Icon(Icons.add),
  // This label is used by Finalrun AND read aloud by screen readers.
  semanticLabel: 'Add to cart', 
  onPressed: () {
    // ...
  },
)

Example Prompt:

Tap on Add to cart

Writing Finalrun Prompts

Finalrun uses a simple, human-readable language to define test steps.

Tapping a Widget

Use the Tap on command to simulate a tap.

Prompts:

# Tapping a button with the text 'Login'
Tap on Login button

# Tapping an icon button with the label 'Settings'
Tap on Settings icon

# Tapping a widget with the identifier 'user_profile_avatar'
Tap on User Profile Avatar

Entering Text

Use the Enter command to input text into fields.

Prompts:

# Entering text into a field identified by its label 'Username'
Enter "john.doe" into Username

# Entering text into a field identified by its identifier 'password_field'
Enter "S3cureP@ssw0rd!" into password field

Asserting Widget Visibility

Use the Assert command to verify that a widget is visible.

Prompts:

# Asserting that text 'Welcome back!' is visible
Verify if "Welcome back!" is visible

# Asserting that a widget with the identifier 'error_message_banner' is visible
Verify that error banner is visible

Best Practices

• Embrace Semantics for Robustness and Accessibility: It is a good practice for your team to prioritize using semanticIdentifier for tests. This decouples your tests from user-facing text that might change. At the same time, always ensure all interactive elements have a proper semanticLabel for accessibility.

• Build Accessibility-Compliant Apps by Default: By adopting these testing practices, your team naturally builds accessibility-compliant applications. Using semanticLabel and thinking about identifiers ensures that all interactive elements are clearly described and identifiable, which is the foundation of a great user experience for those using assistive technologies. Think of testability and accessibility as two sides of the same coin.

• Enforce Testability and Accessibility: Consider creating custom wrapper widgets (e.g., FinalrunButton, FinalrunTextField) that require a semanticIdentifier and/or semanticLabel parameter. You can also set up linting rules in your project to enforce this practice.

A Note on Flutter Keys

Finalrun does not support finding widgets using Flutter's Key property (Key('my-widget')). Keys are an internal Flutter mechanism and are not exposed to the native accessibility layer that Finalrun relies on.

Known Limitations

• No Desktop Support: Finalrun does not currently support testing Flutter applications on Desktop platforms (macOS, Windows, or Linux).