. d updated docs for approval_tests_flutter

examples/flutter_example/pubspec.yaml

@@ -15,8 +15,6 @@ dependencies:
   approval_tests_flutter:
     path: ../../packages/approval_tests_flutter
 
-  cupertino_icons: ^1.0.8
-
 dev_dependencies:
   flutter_lints: ^4.0.0
 

examples/flutter_example/test/widget_test.dart

@@ -13,9 +13,6 @@ void main() {
 
       await tester.approvalTest(
         description: 'should display 0',
-        options: const Options(
-          deleteReceivedFile: false,
-        ),
       );
 
       await tester.tap(find.byType(FloatingActionButton));
@@ -24,9 +21,6 @@ void main() {
 
       await tester.approvalTest(
         description: 'should display 1',
-        options: const Options(
-          deleteReceivedFile: false,
-        ),
       );
     });
   });

packages/approval_tests/README.md

@@ -36,10 +36,21 @@ In normal unit testing, you say `expect(person.getAge(), 5)`. Approvals allow yo
 
 I am writing an implementation of **[Approval Tests](https://approvaltests.com/)** in Dart. If anyone wants to help, please **[text](https://t.me/yelmuratoff)** me. 🙏
 
+## Packages
+ApprovalTests is designed for two level: Dart and Flutter. <br>
+
+| Package | Version | Description | 
+| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| [approval_tests](https://github.com/approvals/ApprovalTests.Dart/tree/feature/approval_tests_flutter/packages/approval_tests) | [![Pub](https://img.shields.io/pub/v/approval_tests.svg?style=flat-square)](https://pub.dev/packages/approval_tests) | **Dart** package for approval testing of `unit` tests *(main)* |
+| [approval_tests_flutter](https://github.com/approvals/ApprovalTests.Dart/tree/feature/approval_tests_flutter/packages/approval_tests_flutter) | [![Pub](https://img.shields.io/pub/v/approval_tests.svg?style=flat-square)](https://pub.dev/packages/approval_tests) | **Flutter** package for approval testing of `widget`, `integration` tests |
+
+
 ## 📋 How it works
 
-- If the changed results match the approved file perfectly, the test passes.
-- If there's a difference, a reporter tool will highlight the mismatch and the test fails.
+- The first run of the test automatically creates an `approved` file if there is no such file.
+- If the changed results match the `approved` file perfectly, the test passes.
+- If there's a difference, a `reporter` tool will highlight the mismatch and the test fails.
+- If the test is passed, the `received` file is deleted automatically. You can change this by changing the `deleteReceivedFile` value in `options`. If the test fails, the received file remains for analysis.
 
 ## 📦 Installation
 
@@ -65,13 +76,13 @@ It comes ready with:
 
 ## 📚 How to use
 
-In order to use Approval Tests, the user needs to:
+In order to use `Approval Tests`, the user needs to:
 
 1. Set up a test: This involves importing the Approval Tests library into your own code.
 
-2. Optionally, set up a reporter: Reporters are tools that highlight differences between approved and received files when a test fails. Although not necessary, they make it significantly easier to see what changes have caused a test to fail. The default reporter is the `CommandLineReporter`. You can also use the `DiffReporter` to compare the files in your IDE.
+2. Optionally, set up a reporter: Reporters are tools that highlight differences between approved and received files when a test fails. Although not necessary, they make it significantly easier to see what changes have caused a test to fail. The default reporter is the `CommandLineReporter`. You can also use the `DiffReporter` to compare the files in your IDE, and the `GitReporter` to see the differences in the `Git GUI`.
 
-3. Manage the "approved" file: When the test is run for the first time, an approved file is created automatically. This file will represent the expected outcome. Once the test results in a favorable outcome, the approved file should be updated to reflect these changes. A little bit below I wrote how to do it.
+3. Manage the `approved` file: When the test is run for the first time, an approved file is created automatically. This file will represent the expected outcome. Once the test results in a favorable outcome, the approved file should be updated to reflect these changes. A little bit below I wrote how to do it.
 
 This setup is useful because it shortens feedback loops, saving developers time by only highlighting what has been altered rather than requiring them to parse through their entire output to see what effect their changes had.
 
@@ -85,6 +96,16 @@ We’ll provide more explanation in due course, but, briefly, here are the most
 Most diff tools have the ability to move text from left to right, and save the result.
 How to use diff tools is just below, there is a `Comparator` class for that.
 
+#### • Via CLI command
+You can run the command in a terminal to review your files:
+```bash
+dart run approval_tests:review
+```
+After running the command, the files will be analyzed and you will be asked to choose one of the options:
+- `y` - Approve the received file.
+- `n` - Reject the received file.
+- `v`iew - View the differences between the received and approved files. After selecting `v` you will be asked which IDE you want to use to view the differences.
+
 #### • Via approveResult property
 If you want the result to be automatically saved after running the test, you need to use the `approveResult` property in `Options`:
 
@@ -167,6 +188,7 @@ You can study it to understand how to use the package to test complex code.
 And the `verify_methods` folder has small examples of using different `ApprovalTests` methods for different cases.
 
 ### JSON example
+With `verifyAsJson`, if you pass data models as `JsonItem`, with nested other models as `AnotherItem` and `SubItem`, then you need to add an `toJson` method to each model for the serialization to succeed.
 
 <!-- snippet: same_verify_as_json_test_with_model -->
 <a id='snippet-same_verify_as_json_test_with_model'></a>

packages/approval_tests_flutter/CHANGELOG.md

@@ -1,10 +1,10 @@
 ## 1.1.0
 
-- Breaking release:
+- **Breaking release**:
    - Added new reporter: `GitReporter`. It allows you to use `git` to view the differences between the received and approved files.
    - Added support to approve files using CLI. Now you can approve files using the command line: `dart run approval_tests:review`
-   - Added support to use ApprovalTests during widget tests.  
-Thanks to [Richard Coutts](https://github.com/buttonsrtoys)
+   - **Approval Tests Flutter**: Added support to use ApprovalTests during widget, integration tests.  
+Thanks to **[Richard Coutts](https://github.com/buttonsrtoys)**
 
 ## 1.0.0
 

packages/approval_tests_flutter/README.md

@@ -6,7 +6,7 @@
 </p>
 </div>
 
-<h2 align="center"> Approval Tests implementation in Dart (Flutter) 🚀 </h2>
+<h2 align="center"> Approval Tests implementation in Flutter 🚀 </h2>
 <br>
 <p align="center">
   <a href="https://app.codecov.io/gh/approvals/ApprovalTests.Dart"><img src="https://codecov.io/gh/approvals/ApprovalTests.Dart/branch/main/graph/badge.svg" alt="codecov"></a>
@@ -36,11 +36,72 @@ In normal unit testing, you say `expect(person.getAge(), 5)`. Approvals allow yo
 
 I am writing an implementation of **[Approval Tests](https://approvaltests.com/)** in Dart. If anyone wants to help, please **[text](https://t.me/yelmuratoff)** me. 🙏
 
+Thanks to **[Richard Coutts](https://github.com/buttonsrtoys)** for special contributions to the `approval_tests_flutter` package.
+
+## Packages
+ApprovalTests is designed for two level: Dart and Flutter. <br>
+
+| Package | Version | Description | 
+| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| [approval_tests](https://github.com/approvals/ApprovalTests.Dart/tree/feature/approval_tests_flutter/packages/approval_tests) | [![Pub](https://img.shields.io/pub/v/approval_tests.svg?style=flat-square)](https://pub.dev/packages/approval_tests) | **Dart** package for approval testing of `unit` tests *(main)* |
+| [approval_tests_flutter](https://github.com/approvals/ApprovalTests.Dart/tree/feature/approval_tests_flutter/packages/approval_tests_flutter) | [![Pub](https://img.shields.io/pub/v/approval_tests.svg?style=flat-square)](https://pub.dev/packages/approval_tests) | **Flutter** package for approval testing of `widget`, `integration` tests |
+
+
 ## 📋 How it works
 
-- If the changed results match the approved file perfectly, the test passes.
-- If there's a difference, a reporter tool will highlight the mismatch and the test fails.
+- The first run of the test automatically creates an `approved` file if there is no such file.
+- If the changed results match the `approved` file perfectly, the test passes.
+- If there's a difference, a `reporter` tool will highlight the mismatch and the test fails.
+- If the test is passed, the `received` file is deleted automatically. You can change this by changing the `deleteReceivedFile` value in `options`. If the test fails, the received file remains for analysis.
+
+Instead of writing:
+```dart
+    testWidgets('home page', (WidgetTester tester) async {
+        await tester.pumpWidget(const MyApp());
+        await tester.pumpAndSettle();
+
+        expect(find.text('You have pushed the button this many times:'), findsOneWidget);
+        expect(find.text('0'), findsOneWidget);
+        expect(find.byWidgetPredicate(
+            (Widget widget) => widget is Text && widget.data == 'hello' && 
+            widget.key == ValueKey('myKey'),
+        ), findsOneWidget);
+        expect(find.text('Approved Example'), findsOneWidget);
+    });
+```
 
+Write this:
+```dart
+    testWidgets('smoke test', (WidgetTester tester) async {
+        await tester.pumpWidget(const MyApp());
+        await tester.pumpAndSettle();
+
+        await tester.approvalTest();
+    });
+```
+
+Suppose you wanted to confirm that a page loaded with all the widget you expected. To do this,
+perform an approval test by calling `tester.approvalTest`, and give your test a suitable name:
+
+```dart
+    testWidget('home page', () {
+        await tester.pumpWidget(const MyApp());
+        await tester.pumpAndSettle();
+
+        await tester.approvalTest(description: 'all widgets load correctly');
+    });
+```
+
+To include your project's custom widget types in your test, and to perform post-test checks, add 
+calls to `Approved.setUpAll()` to your tests' `setUpAll` calls, like so:
+
+```dart
+    main() {
+        setUpAll(() {
+            Approved.setUpAll();
+        });
+    }
+```
 ## 📦 Installation
 
 Add the following to your `pubspec.yaml` file:
@@ -52,26 +113,18 @@ dependencies:
 
 ## 👀 Getting Started
 
-The best way to get started is to download and open the starter project:
-* [Approvaltests.Dart.StarterProject](https://github.com/approvals/Approvaltests.Dart.StarterProject)
-
-This is a standard project that can be imported into any editor or IDE and also includes CI with GitHub Actions.
-
-It comes ready with:
-
-- A suitable `.gitignore` to exclude approval artifacts
-- A ready linter with all rules in place
-- A GitHub action to run tests and you can always check the status of the tests on the badge in the `README.md` file.
+The best way to get started is to download and open the example project:
+* [Flutter example project](https://github.com/approvals/ApprovalTests.Dart/tree/feature/approval_tests_flutter/examples/flutter_example)
 
 ## 📚 How to use
 
-In order to use Approval Tests, the user needs to:
+In order to use `Approval Tests`, the user needs to:
 
 1. Set up a test: This involves importing the Approval Tests library into your own code.
 
-2. Optionally, set up a reporter: Reporters are tools that highlight differences between approved and received files when a test fails. Although not necessary, they make it significantly easier to see what changes have caused a test to fail. The default reporter is the `CommandLineReporter`. You can also use the `DiffReporter` to compare the files in your IDE.
+2. Optionally, set up a reporter: Reporters are tools that highlight differences between approved and received files when a test fails. Although not necessary, they make it significantly easier to see what changes have caused a test to fail. The default reporter is the `CommandLineReporter`. You can also use the `DiffReporter` to compare the files in your IDE, and the `GitReporter` to see the differences in the `Git GUI`.
 
-3. Manage the "approved" file: When the test is run for the first time, an approved file is created automatically. This file will represent the expected outcome. Once the test results in a favorable outcome, the approved file should be updated to reflect these changes. A little bit below I wrote how to do it.
+3. Manage the `approved` file: When the test is run for the first time, an approved file is created automatically. This file will represent the expected outcome. Once the test results in a favorable outcome, the approved file should be updated to reflect these changes. A little bit below I wrote how to do it.
 
 This setup is useful because it shortens feedback loops, saving developers time by only highlighting what has been altered rather than requiring them to parse through their entire output to see what effect their changes had.
 
@@ -85,6 +138,16 @@ We’ll provide more explanation in due course, but, briefly, here are the most
 Most diff tools have the ability to move text from left to right, and save the result.
 How to use diff tools is just below, there is a `Comparator` class for that.
 
+#### • Via CLI command
+You can run the command in a terminal to review your files:
+```bash
+dart run approval_tests:review
+```
+After running the command, the files will be analyzed and you will be asked to choose one of the options:
+- `y` - Approve the received file.
+- `n` - Reject the received file.
+- `v`iew - View the differences between the received and approved files. After selecting `v` you will be asked which IDE you want to use to view the differences.
+
 #### • Via approveResult property
 If you want the result to be automatically saved after running the test, you need to use the `approveResult` property in `Options`:
 
@@ -167,6 +230,7 @@ You can study it to understand how to use the package to test complex code.
 And the `verify_methods` folder has small examples of using different `ApprovalTests` methods for different cases.
 
 ### JSON example
+With `verifyAsJson`, if you pass data models as `JsonItem`, with nested other models as `AnotherItem` and `SubItem`, then you need to add an `toJson` method to each model for the serialization to succeed.
 
 <!-- snippet: same_verify_as_json_test_with_model -->
 <a id='snippet-same_verify_as_json_test_with_model'></a>

packages/approval_tests_flutter/lib/src/widget_meta/matcher_types.dart

@@ -9,30 +9,17 @@ enum MatcherTypes {
 }
 
 extension MatcherTypesExtension on MatcherTypes {
-  Matcher get matcher {
-    switch (this) {
-      case MatcherTypes.findsNothing:
-        return findsNothing;
-      case MatcherTypes.findsOneWidget:
-        return findsOneWidget;
-      case MatcherTypes.findsWidgets:
-        return findsWidgets;
-      default:
-        return findsNothing;
-    }
-  }
+  Matcher get matcher => switch (this) {
+        MatcherTypes.findsNothing => findsNothing,
+        MatcherTypes.findsOneWidget => findsOneWidget,
+        MatcherTypes.findsWidgets => findsWidgets,
+        MatcherTypes.unknown => findsNothing,
+      };
 
-  String get matcherName {
-    switch (this) {
-      case MatcherTypes.findsNothing:
-        return 'findsNothing';
-      case MatcherTypes.findsOneWidget:
-        return 'findsOneWidget';
-      case MatcherTypes.findsWidgets:
-        return 'findsWidgets';
-      case MatcherTypes.unknown:
-      default:
-        return '(Unknown)';
-    }
-  }
+  String get matcherName => switch (this) {
+        MatcherTypes.findsNothing => 'findsNothing',
+        MatcherTypes.findsOneWidget => 'findsOneWidget',
+        MatcherTypes.findsWidgets => 'findsWidgets',
+        MatcherTypes.unknown => '(Unknown)',
+      };
 }