[quick_actions] Add DartDoc and test coverage (flutter#2298)

Michael Klimushyn · web-flow · commit 43f14ab0ec71 · 2019-11-26T09:37:38.000-08:00
Also adds a lint to prevent undocumented DartDocs from being added in
the future.

Some of the APIs were public when they really should have been
`@visibleForTesting` or even private. Added some `@visibleForTesting`
annotations as well.
diff --git a/packages/quick_actions/CHANGELOG.md b/packages/quick_actions/CHANGELOG.md
@@ -1,6 +1,15 @@
+## 0.4.0
+
+- Added missing documentation.
+- **Breaking change**. `channel` and `withMethodChannel` are now
+  `@visibleForTesting`. These methods are for plugin unit tests only and may be
+  removed in the future.
+- **Breaking change**. Removed `runLaunchAction` from public API. This method
+  was not meant to be used by consumers of the plugin.
+
 ## 0.3.3+1
 
-* Update and migrate iOS example project by removing flutter_assets, change 
+* Update and migrate iOS example project by removing flutter_assets, change
   "English" to "en", remove extraneous xcconfigs, update to Xcode 11 build
   settings, and remove ARCHS and DEVELOPMENT_TEAM.
 
diff --git a/packages/quick_actions/analysis_options.yaml b/packages/quick_actions/analysis_options.yaml
diff --git a/packages/quick_actions/example/lib/main.dart b/packages/quick_actions/example/lib/main.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:quick_actions/quick_actions.dart';
 
diff --git a/packages/quick_actions/example/test_driver/quick_actions_e2e_test.dart b/packages/quick_actions/example/test_driver/quick_actions_e2e_test.dart
@@ -10,6 +10,6 @@ Future<void> main() async {
   final FlutterDriver driver = await FlutterDriver.connect();
   final String result =
       await driver.requestData(null, timeout: const Duration(minutes: 1));
-  driver.close();
+  await driver.close();
   exit(result == 'pass' ? 0 : 1);
 }
diff --git a/packages/quick_actions/lib/quick_actions.dart b/packages/quick_actions/lib/quick_actions.dart
@@ -17,6 +17,10 @@ typedef void QuickActionHandler(String type);
 
 /// Home screen quick-action shortcut item.
 class ShortcutItem {
+  /// Constructs an instance with the given [type], [localizedTitle], and
+  /// [icon].
+  ///
+  /// Only [icon] should be nullable. It will remain `null` if unset.
   const ShortcutItem({
     @required this.type,
     @required this.localizedTitle,
@@ -36,14 +40,21 @@ class ShortcutItem {
 
 /// Quick actions plugin.
 class QuickActions {
+  /// Gets an instance of the plugin with the default methodChannel.
+  ///
+  /// [initialize] should be called before using any other methods.
   factory QuickActions() => _instance;
 
+  /// This is a test-only constructor. Do not call this, it can break at any
+  /// time.
   @visibleForTesting
   QuickActions.withMethodChannel(this.channel);
 
   static final QuickActions _instance =
       QuickActions.withMethodChannel(_kChannel);
 
+  /// This is a test-only accessor. Do not call this, it can break at any time.
+  @visibleForTesting
   final MethodChannel channel;
 
   /// Initializes this plugin.
@@ -54,10 +65,6 @@ class QuickActions {
       assert(call.method == 'launch');
       handler(call.arguments);
     });
-    runLaunchAction(handler);
-  }
-
-  void runLaunchAction(QuickActionHandler handler) async {
     final String action = await channel.invokeMethod<String>('getLaunchAction');
     if (action != null) {
       handler(action);
diff --git a/packages/quick_actions/pubspec.yaml b/packages/quick_actions/pubspec.yaml
@@ -3,7 +3,7 @@ description: Flutter plugin for creating shortcuts on home screen, also known as
   Quick Actions on iOS and App Shortcuts on Android.
 author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/quick_actions
-version: 0.3.3+1
+version: 0.4.0
 
 flutter:
   plugin:
diff --git a/packages/quick_actions/test/quick_actions_test.dart b/packages/quick_actions/test/quick_actions_test.dart
@@ -1,6 +1,8 @@
 // Copyright 2017 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
+import 'dart:async';
+
 import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:quick_actions/quick_actions.dart';
@@ -16,7 +18,7 @@ void main() {
     quickActions.channel.setMockMethodCallHandler(
       (MethodCall methodCall) async {
         log.add(methodCall);
-        return null;
+        return 'non empty response';
       },
     );
   });
@@ -59,14 +61,30 @@ void main() {
     log.clear();
   });
 
-  test('runLaunchAction', () {
-    quickActions.runLaunchAction(null);
+  test('initialize', () async {
+    final Completer<bool> quickActionsHandler = Completer<bool>();
+    quickActions.initialize((_) => quickActionsHandler.complete(true));
     expect(
       log,
       <Matcher>[
         isMethodCall('getLaunchAction', arguments: null),
       ],
     );
     log.clear();
+
+    expect(quickActionsHandler.future, completion(isTrue));
+  });
+
+  test('Shortcut item can be constructed', () {
+    const String type = 'type';
+    const String localizedTitle = 'title';
+    const String icon = 'foo';
+
+    const ShortcutItem item =
+        ShortcutItem(type: type, localizedTitle: localizedTitle, icon: icon);
+
+    expect(item.type, type);
+    expect(item.localizedTitle, localizedTitle);
+    expect(item.icon, icon);
   });
 }

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,6 @@ Future<void> main() async {`
`10`	`10`	`final FlutterDriver driver = await FlutterDriver.connect();`
`11`	`11`	`final String result =`
`12`	`12`	`await driver.requestData(null, timeout: const Duration(minutes: 1));`
`13`		`- driver.close();`
	`13`	`+ await driver.close();`
`14`	`14`	`exit(result == 'pass' ? 0 : 1);`
`15`	`15`	`}`