Generate Finder

Annotate the main() function of your test file with the @Match annotation. Pass a list of widget types to the finders param to generate a finder counterpart.

@Match(finders: [MyWidget, HomeScreen, ItemListView])
void main() {
    //Test code in here
}

A ${my_test_file}.finders.dart file containing generated custom finder classes is created after running the generation command. The generated custom finders are private by default and expose a global variable or function for use.

Naming convention

Generated finder class names follow the pattern _${MyWidgetName}MatchFinder.

class _MyWidgetMatchFinder extends MatchFinder {
    //Generated code 
}

The exposed global variable or function name is prefixed with the word 'find' followed by the widget name.

final findMyWidget = _MyWidgetMatchFinder();

findMyWidget(String text) => _MyWidgetMatchFinder(text: text);

Annotated declarations

The generated code will contain a constructor field for every declaration marked without a default value.

findMyWidget(String text) => _MyWidgetMatchFinder(text: text);

class _MyWidgetMatchFinder extends MatchFinder {
  _MyWidgetMatchFinder({
    required String text,
  })  : _text = text;

  final String _text;
  
  ...
}

Generic widget support

In cases of a generic type widget, finder-gen-matcher takes this into account.

Assuming we have a generic widget.

class MyGenericWidget<K, V> extends StatelessWidget {
    /// Widget code
}

The generated code header output will be:

findMyGenericWidget<K, V>() => _MyGenericWidgetMatchFinder<K, V>();

Usage

Import the finder path to your test file:

import '${my_test_file}.finders.dart';

Use the generated finder by passing it as the first argument to the expect() function in your test file.

  testWidgets('Ensures MyWidget is found', (WidgetTester tester) async {
  
    await _pumpApp(tester);

    /// The [findMyWidget] is generated by this tool
    expect(findMyWidget, findsOneWidget);

    /// The [findMyGenericWidget<K, V>()] is generated by this tool
    expect(findMyGenericWidget<String, int>(), findsOneWidget);

    /// The [findMySpecificWidget(required bool isSpecific)] is generated by this tool
    expect(findMySpecificWidget(isSpecific: true), findsOneWidget);
  });

Handling Exceptions

While running the command to generate files, you might encounter some build failures. The table below summarises the exceptions that are likely to be thrown during development to better equip you in resolving them.

To request a feature or file an issue check out the GitHub page.