Repository navigation
[material_ui, cupertino_ui] Add unit tests for snippets #188530
Description
(This issue is linked by TODO comments in flutter/packages.)
There are many code snippets in the API doc that were once {@tool snippet} and were not covered by unit tests. We should add unit tests to avoid bit rot.
Solution 1: #region directives (recommended)
The Dart team has completed a new feature, the #region directive, where we can specify only a part of an example file to be imported by the API doc. dart-lang/dartdoc#4253
Solution 2: Code excerpts
Code excerpts are an existing mechanism in flutter/packages's CI workflow to guarantee two snippets across different files are identical. It is currently only applied to READMEs. This might need prerequisite work to expand its support to source files.
Expected format
Example:
// packages/material_ui/lib/src/circle_avatar.dart
/// <example>
///
/// If the avatar is to have an image, the image should be specified in the
/// [backgroundImage] property:
///
// @code-excerpt "../../tests/circle_avatar_test.dart (basic)"
/// ```dart
/// final avatar = CircleAvatar(
/// backgroundImage: NetworkImage(userAvatarUrl),
/// );
/// ```
///
/// </example>// packages/material_ui/test/circle_avatar_test.dart
void main() {
testWidgets('CircleAvatar basic example', (WidgetTester tester) async {
// #docregion basic
final avatar = CircleAvatar(
backgroundImage: NetworkImage(userAvatarUrl),
);
// #enddocregion basic
// Test the widget works as expected here...
});
}
Activity
dkwingsmt commentedon Sep 25, 2026
I've conducted an analysis throughout the
flutter/packagesrepository. After excluding some non-significant items (which we'll come back to later), the list of TODO are listed below. The list is divided into batches of size 3~7 for the convenience of reviewers.Part 1:
packages/cupertino_ui(25 items, Batches 1–5)Batch 1:
CupertinoApp(5 items)Batch 2:
CupertinoSwitch(5 items)CupertinoSwitchinsideCupertinoListTileandMergeSemantics)Batch 3:
CupertinoDynamicColor&CupertinoContextMenu(5 items)CupertinoDynamicColorinCupertinoThemeData)CupertinoDynamicColor.resolve)Batch 4: Cupertino Pickers, Slider & Segmented Control (5 items)
Batch 5: Cupertino Text Fields, Magnifier & Icons (5 items)
Part 2:
packages/material_ui(130 items, Batches 6–23)Batch 6:
MaterialApp(5 items)homeScaffold)routesmap)themeconfiguration)Batch 7:
AppBar,SliverAppBar,BottomAppBar&Scaffold(5 items)Batch 8:
Switch(5 items)material_ui.switch.thumbColortemplate)material_ui.switch.trackColortemplate)material_ui.switch.trackOutlineColortemplate)material_ui.switch.trackOutlineWidthtemplate)material_ui.switch.thumbIcontemplate)Batch 9:
Checkbox,CheckboxListTile,Radio&RadioListTile(5 items)material_ui.checkbox.fillColortemplate)material_ui.radio.fillColortemplate)Batch 10:
ListTile&SwitchListTile(6 items)Card+ListTilesamples)ListTile)ListTile)ListTile)Batch 11:
Chip&ChipTheme(5 items)Batch 12:
Dialog,AlertDialog&SimpleDialog(5 items)Batch 13:
Slider&SliderTheme(6 items)Batch 14:
RangeSlider(4 items)Batch 15: Menus (
DropdownMenu,MenuAnchor&PopupMenu) (6 items)Batch 16:
Tab,TabController,DefaultTabController&DrawerController(6 items)Batch 17: Text Input, Selection & Search (6 items)
SelectableText.rich)Batch 18:
TimeOfDay&showTimePicker(4 items)Directionality)alwaysUse24HourFormat)Batch 19:
Divider,VerticalDivider,Ink&InkSparkle(6 items)material_ui.Divider.colortemplate)InkwithInkWell)Ink.image)Batch 20:
CarouselView,CircleAvatar,SegmentedButton&Icons(7 items)backgroundImagesample)Textsample)Batch 21:
ThemeData,TextTheme,ProgressIndicatorTheme&TooltipTheme(5 items)Batch 22:
MaterialState&ColorScheme(7 items)Batch 23:
ColorsClass Doc & SwatchesColors.green[400])Container(color: Colors.blue))[material_ui] Migrate AppBar, SliverAppBar, BottomAppBar, and Scaffol…
[material_ui] Migrate MaterialApp API doc snippets to {@example} and …
[material_ui] Migrate `Switch` API doc snippets to {@example} (batch …
[material_ui] Migrate Checkbox, CheckboxListTile, Radio, and RadioLis…
[material_ui] Migrate ListTile and SwitchListTile API doc snippets to {…