diff --git a/packages/camera/camera_android_camerax/example/README.md b/packages/camera/camera_android_camerax/example/README.md index 438e446d1921..96b8bb17dbff 100644 --- a/packages/camera/camera_android_camerax/example/README.md +++ b/packages/camera/camera_android_camerax/example/README.md @@ -1,3 +1,9 @@ -# camera_android_camerax_example +# Platform Implementation Test App -Demonstrates how to use the camera_android_camerax plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/camera/camera_web/example/README.md b/packages/camera/camera_web/example/README.md index 8a6e74b107ea..0e51ae5ecbd2 100644 --- a/packages/camera/camera_web/example/README.md +++ b/packages/camera/camera_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. @@ -6,4 +16,4 @@ See [Plugin Tests > Web Tests](https://github.com/flutter/flutter/wiki/Plugin-Te in the Flutter wiki for instructions to setup and run the tests in this package. Check [flutter.dev > Integration testing](https://flutter.dev/docs/testing/integration-tests) -for more info. \ No newline at end of file +for more info. diff --git a/packages/camera/camera_windows/example/README.md b/packages/camera/camera_windows/example/README.md index ee7326472eaf..96b8bb17dbff 100644 --- a/packages/camera/camera_windows/example/README.md +++ b/packages/camera/camera_windows/example/README.md @@ -1,3 +1,9 @@ -# camera_windows_example +# Platform Implementation Test App -Demonstrates how to use the camera_windows plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/file_selector/file_selector_ios/example/README.md b/packages/file_selector/file_selector_ios/example/README.md index 9ed63fdb669f..96b8bb17dbff 100644 --- a/packages/file_selector/file_selector_ios/example/README.md +++ b/packages/file_selector/file_selector_ios/example/README.md @@ -1,4 +1,9 @@ -# `file_selector_ios` example +# Platform Implementation Test App -Demonstrates iOS implementation of the -[`file_selector` plugin](https://pub.dev/packages/file_selector). \ No newline at end of file +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/file_selector/file_selector_linux/example/README.md b/packages/file_selector/file_selector_linux/example/README.md index 2f9f8c0f824b..96b8bb17dbff 100644 --- a/packages/file_selector/file_selector_linux/example/README.md +++ b/packages/file_selector/file_selector_linux/example/README.md @@ -1,4 +1,9 @@ -# `file_selector_linux` example +# Platform Implementation Test App -Demonstrates Linux implementation of the -[`file_selector` plugin](https://pub.dev/packages/file_selector). +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/file_selector/file_selector_macos/example/README.md b/packages/file_selector/file_selector_macos/example/README.md index 782fe679fcb0..96b8bb17dbff 100644 --- a/packages/file_selector/file_selector_macos/example/README.md +++ b/packages/file_selector/file_selector_macos/example/README.md @@ -1,4 +1,9 @@ -# `file_selector_macos` example +# Platform Implementation Test App -Demonstrates macOS implementation of the -[`file_selector` plugin](https://pub.dev/packages/file_selector). +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/file_selector/file_selector_web/example/README.md b/packages/file_selector/file_selector_web/example/README.md index 8a6e74b107ea..0e51ae5ecbd2 100644 --- a/packages/file_selector/file_selector_web/example/README.md +++ b/packages/file_selector/file_selector_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. @@ -6,4 +16,4 @@ See [Plugin Tests > Web Tests](https://github.com/flutter/flutter/wiki/Plugin-Te in the Flutter wiki for instructions to setup and run the tests in this package. Check [flutter.dev > Integration testing](https://flutter.dev/docs/testing/integration-tests) -for more info. \ No newline at end of file +for more info. diff --git a/packages/file_selector/file_selector_windows/example/README.md b/packages/file_selector/file_selector_windows/example/README.md index c8a3cce44a9a..96b8bb17dbff 100644 --- a/packages/file_selector/file_selector_windows/example/README.md +++ b/packages/file_selector/file_selector_windows/example/README.md @@ -1,4 +1,9 @@ -# `file_selector_windows` Example +# Platform Implementation Test App -Demonstrates Windows implementation of the -[`file_selector` plugin](https://pub.dev/packages/file_selector). +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/google_maps_flutter/google_maps_flutter_android/example/README.md b/packages/google_maps_flutter/google_maps_flutter_android/example/README.md index c8852649b065..96b8bb17dbff 100644 --- a/packages/google_maps_flutter/google_maps_flutter_android/example/README.md +++ b/packages/google_maps_flutter/google_maps_flutter_android/example/README.md @@ -1,3 +1,9 @@ -# google_maps_flutter_example +# Platform Implementation Test App -Demonstrates how to use the google_maps_flutter plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/google_maps_flutter/google_maps_flutter_ios/example/README.md b/packages/google_maps_flutter/google_maps_flutter_ios/example/README.md index c8852649b065..96b8bb17dbff 100644 --- a/packages/google_maps_flutter/google_maps_flutter_ios/example/README.md +++ b/packages/google_maps_flutter/google_maps_flutter_ios/example/README.md @@ -1,3 +1,9 @@ -# google_maps_flutter_example +# Platform Implementation Test App -Demonstrates how to use the google_maps_flutter plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/google_maps_flutter/google_maps_flutter_web/example/README.md b/packages/google_maps_flutter/google_maps_flutter_web/example/README.md index 3cdecfab2ab9..0e51ae5ecbd2 100644 --- a/packages/google_maps_flutter/google_maps_flutter_web/example/README.md +++ b/packages/google_maps_flutter/google_maps_flutter_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. @@ -7,6 +17,3 @@ in the Flutter wiki for instructions to setup and run the tests in this package. Check [flutter.dev > Integration testing](https://flutter.dev/docs/testing/integration-tests) for more info. - -See [Plugin Tests > Web Tests > Mocks](https://github.com/flutter/flutter/wiki/Plugin-Tests#mocks) -in the Flutter wiki for more information about the `.mocks.dart` files in this package. \ No newline at end of file diff --git a/packages/google_sign_in/google_sign_in_android/example/README.md b/packages/google_sign_in/google_sign_in_android/example/README.md index 8eb153eb8efd..96b8bb17dbff 100644 --- a/packages/google_sign_in/google_sign_in_android/example/README.md +++ b/packages/google_sign_in/google_sign_in_android/example/README.md @@ -1,3 +1,9 @@ -# google_sign_in_android example +# Platform Implementation Test App -Exercises the Android implementation of `GoogleSignInPlatform`. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/google_sign_in/google_sign_in_ios/example/README.md b/packages/google_sign_in/google_sign_in_ios/example/README.md index 04c3372dc3b0..96b8bb17dbff 100644 --- a/packages/google_sign_in/google_sign_in_ios/example/README.md +++ b/packages/google_sign_in/google_sign_in_ios/example/README.md @@ -1,3 +1,9 @@ -# google_sign_in_ios example +# Platform Implementation Test App -Exercises the iOS implementation of `GoogleSignInPlatform`. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/google_sign_in/google_sign_in_web/example/README.md b/packages/google_sign_in/google_sign_in_web/example/README.md index 8a6e74b107ea..0e51ae5ecbd2 100644 --- a/packages/google_sign_in/google_sign_in_web/example/README.md +++ b/packages/google_sign_in/google_sign_in_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. @@ -6,4 +16,4 @@ See [Plugin Tests > Web Tests](https://github.com/flutter/flutter/wiki/Plugin-Te in the Flutter wiki for instructions to setup and run the tests in this package. Check [flutter.dev > Integration testing](https://flutter.dev/docs/testing/integration-tests) -for more info. \ No newline at end of file +for more info. diff --git a/packages/image_picker/image_picker_android/example/README.md b/packages/image_picker/image_picker_android/example/README.md index 16b5c51839f8..96b8bb17dbff 100755 --- a/packages/image_picker/image_picker_android/example/README.md +++ b/packages/image_picker/image_picker_android/example/README.md @@ -1,3 +1,9 @@ -# image_picker_example +# Platform Implementation Test App -Demonstrates how to use the `image_picker` plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/image_picker/image_picker_for_web/example/README.md b/packages/image_picker/image_picker_for_web/example/README.md index 4348451b14e2..0e51ae5ecbd2 100644 --- a/packages/image_picker/image_picker_for_web/example/README.md +++ b/packages/image_picker/image_picker_for_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. diff --git a/packages/image_picker/image_picker_ios/example/README.md b/packages/image_picker/image_picker_ios/example/README.md index 16b5c51839f8..96b8bb17dbff 100755 --- a/packages/image_picker/image_picker_ios/example/README.md +++ b/packages/image_picker/image_picker_ios/example/README.md @@ -1,3 +1,9 @@ -# image_picker_example +# Platform Implementation Test App -Demonstrates how to use the `image_picker` plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/image_picker/image_picker_windows/example/README.md b/packages/image_picker/image_picker_windows/example/README.md index 7f61053c6e30..96b8bb17dbff 100644 --- a/packages/image_picker/image_picker_windows/example/README.md +++ b/packages/image_picker/image_picker_windows/example/README.md @@ -1,3 +1,9 @@ -# image_picker_windows_example +# Platform Implementation Test App -Demonstrates how to use the image_picker_windows plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/in_app_purchase/in_app_purchase_android/example/README.md b/packages/in_app_purchase/in_app_purchase_android/example/README.md index 255e838e5b93..96b8bb17dbff 100644 --- a/packages/in_app_purchase/in_app_purchase_android/example/README.md +++ b/packages/in_app_purchase/in_app_purchase_android/example/README.md @@ -1,58 +1,9 @@ -# In App Purchase Example +# Platform Implementation Test App -Demonstrates how to use the In App Purchase Android (IAP) Plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. -## Getting Started - -### Preparation - -There's a significant amount of setup required for testing in-app purchases -successfully, including registering new app IDs and store entries to use for -testing in the Play Developer Console. Google Play requires developers to -configure an app with in-app items for purchase to call their in-app-purchase -APIs. The Google Play Store has extensive documentation on how to do this, and -we've also included a high level guide below. - -* [Google Play Billing Overview](https://developer.android.com/google/play/billing/billing_overview) - -### Android - -1. Create a new app in the [Play Developer - Console](https://play.google.com/apps/publish/) (PDC). - -2. Sign up for a merchant's account in the PDC. - -3. Create IAPs in the PDC available for purchase in the app. The example assumes - the following SKU IDs exist: - - - `consumable`: A managed product. - - `upgrade`: A managed product. - - `subscription_silver`: A lower level subscription. - - `subscription_gold`: A higher level subscription. - - Make sure that all of the products are set to `ACTIVE`. - -4. Update `APP_ID` in `example/android/app/build.gradle` to match your package - ID in the PDC. - -5. Create an `example/android/keystore.properties` file with all your signing - information. `keystore.example.properties` exists as an example to follow. - It's impossible to use any of the `BillingClient` APIs from an unsigned APK. - See - [here](https://developer.android.com/studio/publish/app-signing#secure-shared-keystore) - and [here](https://developer.android.com/studio/publish/app-signing#sign-apk) - for more information. - -6. Build a signed apk. `flutter build apk` will work for this, the gradle files - in this project have been configured to sign even debug builds. - -7. Upload the signed APK from step 6 to the PDC, and publish that to the alpha - test channel. Add your test account as an approved tester. The - `BillingClient` APIs won't work unless the app has been fully published to - the alpha channel and is being used by an authorized test account. See - [here](https://support.google.com/googleplay/android-developer/answer/3131213) - for more info. - -8. Sign in to the test device with the test account from step #7. Then use - `flutter run` to install the app to the device and test like normal. - \ No newline at end of file +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/in_app_purchase/in_app_purchase_storekit/example/README.md b/packages/in_app_purchase/in_app_purchase_storekit/example/README.md index 9cf98bf02e79..96b8bb17dbff 100644 --- a/packages/in_app_purchase/in_app_purchase_storekit/example/README.md +++ b/packages/in_app_purchase/in_app_purchase_storekit/example/README.md @@ -1,75 +1,9 @@ -# In App Purchase iOS Example +# Platform Implementation Test App -Demonstrates how to use the In App Purchase iOS (IAP) Plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. -## Getting Started - -### Preparation - -There's a significant amount of setup required for testing in app purchases -successfully, including registering new app IDs and store entries to use for -testing in App Store Connect. The App Store requires developers to configure -an app with in-app items for purchase to call their in-app-purchase APIs. -The App Store has extensive documentation on how to do this, and we've also -included a high level guide below. - -* [In-App Purchase (App Store)](https://developer.apple.com/in-app-purchase/) - -### iOS - -When using Xcode 12 and iOS 14 or higher you can run the example in the simulator or on a device without -having to configure an App in App Store Connect. The example app is set up to use StoreKit Testing configured -in the `example/ios/Runner/Configuration.storekit` file (as documented in the article [Setting Up StoreKit Testing in Xcode](https://developer.apple.com/documentation/xcode/setting_up_storekit_testing_in_xcode?language=objc)). -To run the application take the following steps (note that it will only work when running from Xcode): - -1. Open the example app with Xcode, `File > Open File` `example/ios/Runner.xcworkspace`; - -2. Within Xcode edit the current scheme, `Product > Scheme > Edit Scheme...` (or press `Command + Shift + ,`); - -3. Enable StoreKit testing: - a. Select the `Run` action; - b. Click `Options` in the action settings; - c. Select the `Configuration.storekit` for the StoreKit Configuration option. - -4. Click the `Close` button to close the scheme editor; - -5. Select the device you want to run the example App on; - -6. Run the application using `Product > Run` (or hit the run button). - -When testing on pre-iOS 14 you can't run the example app on a simulator and you will need to configure an app in App Store Connect. You can do so by following the steps below: - -1. Follow ["Workflow for configuring in-app - purchases"](https://help.apple.com/app-store-connect/#/devb57be10e7), a - detailed guide on all the steps needed to enable IAPs for an app. Complete - steps 1 ("Sign a Paid Applications Agreement") and 2 ("Configure in-app - purchases"). - - For step #2, "Configure in-app purchases in App Store Connect," you'll want - to create the following products: - - - A consumable with product ID `consumable` - - An upgrade with product ID `upgrade` - - An auto-renewing subscription with product ID `subscription_silver` - - An non-renewing subscription with product ID `subscription_gold` - -2. In XCode, `File > Open File` `example/ios/Runner.xcworkspace`. Update the - Bundle ID to match the Bundle ID of the app created in step #1. - -3. [Create a Sandbox tester - account](https://help.apple.com/app-store-connect/#/dev8b997bee1) to test the - in-app purchases with. - -4. Use `flutter run` to install the app and test it. Note that you need to test - it on a real device instead of a simulator. Next click on one of the products - in the example App, this enables the "SANDBOX ACCOUNT" section in the iOS - settings. You will now be asked to sign in with your sandbox test account to - complete the purchase (no worries you won't be charged). If for some reason - you aren't asked to sign-in or the wrong user is listed, go into the iOS - settings ("Settings" -> "App Store" -> "SANDBOX ACCOUNT") and update your - sandbox account from there. This procedure is explained in great detail in - the [Testing In-App Purchases with Sandbox](https://developer.apple.com/documentation/storekit/in-app_purchase/testing_in-app_purchases_with_sandbox?language=objc) article. - - -**Important:** signing into any production service (including iTunes!) with the -sandbox test account will permanently invalidate it. +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/local_auth/local_auth_android/example/README.md b/packages/local_auth/local_auth_android/example/README.md index bd004a77d86b..96b8bb17dbff 100644 --- a/packages/local_auth/local_auth_android/example/README.md +++ b/packages/local_auth/local_auth_android/example/README.md @@ -1,3 +1,9 @@ -# local_auth_example +# Platform Implementation Test App -Demonstrates how to use the local_auth plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/local_auth/local_auth_ios/example/README.md b/packages/local_auth/local_auth_ios/example/README.md index bd004a77d86b..96b8bb17dbff 100644 --- a/packages/local_auth/local_auth_ios/example/README.md +++ b/packages/local_auth/local_auth_ios/example/README.md @@ -1,3 +1,9 @@ -# local_auth_example +# Platform Implementation Test App -Demonstrates how to use the local_auth plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/local_auth/local_auth_windows/example/README.md b/packages/local_auth/local_auth_windows/example/README.md index 8f48b8563cad..96b8bb17dbff 100644 --- a/packages/local_auth/local_auth_windows/example/README.md +++ b/packages/local_auth/local_auth_windows/example/README.md @@ -1,3 +1,9 @@ -# local_auth_example +# Platform Implementation Test App -Demonstrates how to use the local_auth plugin. \ No newline at end of file +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/path_provider/path_provider_android/example/README.md b/packages/path_provider/path_provider_android/example/README.md index 801f44409938..96b8bb17dbff 100644 --- a/packages/path_provider/path_provider_android/example/README.md +++ b/packages/path_provider/path_provider_android/example/README.md @@ -1,3 +1,9 @@ -# path_provider_example +# Platform Implementation Test App -Demonstrates how to use the path_provider plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/path_provider/path_provider_ios/example/README.md b/packages/path_provider/path_provider_ios/example/README.md index 801f44409938..96b8bb17dbff 100644 --- a/packages/path_provider/path_provider_ios/example/README.md +++ b/packages/path_provider/path_provider_ios/example/README.md @@ -1,3 +1,9 @@ -# path_provider_example +# Platform Implementation Test App -Demonstrates how to use the path_provider plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/path_provider/path_provider_linux/example/README.md b/packages/path_provider/path_provider_linux/example/README.md index 333d0f55cec7..96b8bb17dbff 100644 --- a/packages/path_provider/path_provider_linux/example/README.md +++ b/packages/path_provider/path_provider_linux/example/README.md @@ -1,3 +1,9 @@ -# path_provider_linux_example +# Platform Implementation Test App -Demonstrates how to use the path_provider_linux plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/path_provider/path_provider_macos/example/README.md b/packages/path_provider/path_provider_macos/example/README.md index 158869595c01..96b8bb17dbff 100644 --- a/packages/path_provider/path_provider_macos/example/README.md +++ b/packages/path_provider/path_provider_macos/example/README.md @@ -1,3 +1,9 @@ -# path_provider_macos_example +# Platform Implementation Test App -Demonstrates how to use the path_provider_macos plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/path_provider/path_provider_windows/example/README.md b/packages/path_provider/path_provider_windows/example/README.md index 63723991a2e9..96b8bb17dbff 100644 --- a/packages/path_provider/path_provider_windows/example/README.md +++ b/packages/path_provider/path_provider_windows/example/README.md @@ -1,3 +1,9 @@ -# path_provider_windows_example +# Platform Implementation Test App -Demonstrates how to use the path_provider_windows plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/quick_actions/quick_actions_android/example/README.md b/packages/quick_actions/quick_actions_android/example/README.md index c8a629019fc9..96b8bb17dbff 100644 --- a/packages/quick_actions/quick_actions_android/example/README.md +++ b/packages/quick_actions/quick_actions_android/example/README.md @@ -1,3 +1,9 @@ -# quick_actions_example +# Platform Implementation Test App -Demonstrates how to use the quick_actions plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/quick_actions/quick_actions_ios/example/README.md b/packages/quick_actions/quick_actions_ios/example/README.md index c8a629019fc9..96b8bb17dbff 100644 --- a/packages/quick_actions/quick_actions_ios/example/README.md +++ b/packages/quick_actions/quick_actions_ios/example/README.md @@ -1,3 +1,9 @@ -# quick_actions_example +# Platform Implementation Test App -Demonstrates how to use the quick_actions plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/shared_preferences/shared_preferences_android/example/README.md b/packages/shared_preferences/shared_preferences_android/example/README.md index c060637c7ec5..96b8bb17dbff 100644 --- a/packages/shared_preferences/shared_preferences_android/example/README.md +++ b/packages/shared_preferences/shared_preferences_android/example/README.md @@ -1,3 +1,9 @@ -# shared_preferences_example +# Platform Implementation Test App -Demonstrates how to use the shared_preferences plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/shared_preferences/shared_preferences_ios/example/README.md b/packages/shared_preferences/shared_preferences_ios/example/README.md index c060637c7ec5..96b8bb17dbff 100644 --- a/packages/shared_preferences/shared_preferences_ios/example/README.md +++ b/packages/shared_preferences/shared_preferences_ios/example/README.md @@ -1,3 +1,9 @@ -# shared_preferences_example +# Platform Implementation Test App -Demonstrates how to use the shared_preferences plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/shared_preferences/shared_preferences_linux/example/README.md b/packages/shared_preferences/shared_preferences_linux/example/README.md index c060637c7ec5..96b8bb17dbff 100644 --- a/packages/shared_preferences/shared_preferences_linux/example/README.md +++ b/packages/shared_preferences/shared_preferences_linux/example/README.md @@ -1,3 +1,9 @@ -# shared_preferences_example +# Platform Implementation Test App -Demonstrates how to use the shared_preferences plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/shared_preferences/shared_preferences_macos/example/README.md b/packages/shared_preferences/shared_preferences_macos/example/README.md index c060637c7ec5..96b8bb17dbff 100644 --- a/packages/shared_preferences/shared_preferences_macos/example/README.md +++ b/packages/shared_preferences/shared_preferences_macos/example/README.md @@ -1,3 +1,9 @@ -# shared_preferences_example +# Platform Implementation Test App -Demonstrates how to use the shared_preferences plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/shared_preferences/shared_preferences_web/example/README.md b/packages/shared_preferences/shared_preferences_web/example/README.md index 4348451b14e2..0e51ae5ecbd2 100644 --- a/packages/shared_preferences/shared_preferences_web/example/README.md +++ b/packages/shared_preferences/shared_preferences_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. diff --git a/packages/shared_preferences/shared_preferences_windows/example/README.md b/packages/shared_preferences/shared_preferences_windows/example/README.md index 30c7f7e50c3b..96b8bb17dbff 100644 --- a/packages/shared_preferences/shared_preferences_windows/example/README.md +++ b/packages/shared_preferences/shared_preferences_windows/example/README.md @@ -1,3 +1,9 @@ -# shared_preferences_windows_example +# Platform Implementation Test App -Demonstrates how to use the shared_preferences_windows plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/url_launcher/url_launcher_android/example/README.md b/packages/url_launcher/url_launcher_android/example/README.md index 35b4bdb7031e..96b8bb17dbff 100644 --- a/packages/url_launcher/url_launcher_android/example/README.md +++ b/packages/url_launcher/url_launcher_android/example/README.md @@ -1,3 +1,9 @@ -# url_launcher_example +# Platform Implementation Test App -Demonstrates how to use the url_launcher plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/url_launcher/url_launcher_ios/example/README.md b/packages/url_launcher/url_launcher_ios/example/README.md index 35b4bdb7031e..96b8bb17dbff 100644 --- a/packages/url_launcher/url_launcher_ios/example/README.md +++ b/packages/url_launcher/url_launcher_ios/example/README.md @@ -1,3 +1,9 @@ -# url_launcher_example +# Platform Implementation Test App -Demonstrates how to use the url_launcher plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/url_launcher/url_launcher_linux/example/README.md b/packages/url_launcher/url_launcher_linux/example/README.md index 35b4bdb7031e..96b8bb17dbff 100644 --- a/packages/url_launcher/url_launcher_linux/example/README.md +++ b/packages/url_launcher/url_launcher_linux/example/README.md @@ -1,3 +1,9 @@ -# url_launcher_example +# Platform Implementation Test App -Demonstrates how to use the url_launcher plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/url_launcher/url_launcher_macos/example/README.md b/packages/url_launcher/url_launcher_macos/example/README.md index 35b4bdb7031e..96b8bb17dbff 100644 --- a/packages/url_launcher/url_launcher_macos/example/README.md +++ b/packages/url_launcher/url_launcher_macos/example/README.md @@ -1,3 +1,9 @@ -# url_launcher_example +# Platform Implementation Test App -Demonstrates how to use the url_launcher plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/url_launcher/url_launcher_web/example/README.md b/packages/url_launcher/url_launcher_web/example/README.md index 3cdecfab2ab9..0e51ae5ecbd2 100644 --- a/packages/url_launcher/url_launcher_web/example/README.md +++ b/packages/url_launcher/url_launcher_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. @@ -7,6 +17,3 @@ in the Flutter wiki for instructions to setup and run the tests in this package. Check [flutter.dev > Integration testing](https://flutter.dev/docs/testing/integration-tests) for more info. - -See [Plugin Tests > Web Tests > Mocks](https://github.com/flutter/flutter/wiki/Plugin-Tests#mocks) -in the Flutter wiki for more information about the `.mocks.dart` files in this package. \ No newline at end of file diff --git a/packages/url_launcher/url_launcher_windows/example/README.md b/packages/url_launcher/url_launcher_windows/example/README.md index e444852697b9..96b8bb17dbff 100644 --- a/packages/url_launcher/url_launcher_windows/example/README.md +++ b/packages/url_launcher/url_launcher_windows/example/README.md @@ -1,3 +1,9 @@ -# url_launcher_windows_example +# Platform Implementation Test App -Demonstrates the url_launcher_windows plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/video_player/video_player_android/example/README.md b/packages/video_player/video_player_android/example/README.md index f5974e947c00..96b8bb17dbff 100644 --- a/packages/video_player/video_player_android/example/README.md +++ b/packages/video_player/video_player_android/example/README.md @@ -1,3 +1,9 @@ -# video_player_example +# Platform Implementation Test App -Demonstrates how to use the video_player plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/video_player/video_player_avfoundation/example/README.md b/packages/video_player/video_player_avfoundation/example/README.md index f5974e947c00..96b8bb17dbff 100644 --- a/packages/video_player/video_player_avfoundation/example/README.md +++ b/packages/video_player/video_player_avfoundation/example/README.md @@ -1,3 +1,9 @@ -# video_player_example +# Platform Implementation Test App -Demonstrates how to use the video_player plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/video_player/video_player_web/example/README.md b/packages/video_player/video_player_web/example/README.md index 8a6e74b107ea..0e51ae5ecbd2 100644 --- a/packages/video_player/video_player_web/example/README.md +++ b/packages/video_player/video_player_web/example/README.md @@ -1,4 +1,14 @@ -# Testing +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. + +## Testing This package uses `package:integration_test` to run its tests in a web browser. @@ -6,4 +16,4 @@ See [Plugin Tests > Web Tests](https://github.com/flutter/flutter/wiki/Plugin-Te in the Flutter wiki for instructions to setup and run the tests in this package. Check [flutter.dev > Integration testing](https://flutter.dev/docs/testing/integration-tests) -for more info. \ No newline at end of file +for more info. diff --git a/packages/webview_flutter/webview_flutter_android/example/README.md b/packages/webview_flutter/webview_flutter_android/example/README.md index e5bd6e20db63..96b8bb17dbff 100644 --- a/packages/webview_flutter/webview_flutter_android/example/README.md +++ b/packages/webview_flutter/webview_flutter_android/example/README.md @@ -1,3 +1,9 @@ -# webview_flutter_example +# Platform Implementation Test App -Demonstrates how to use the webview_flutter plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/webview_flutter/webview_flutter_web/example/README.md b/packages/webview_flutter/webview_flutter_web/example/README.md index e5bd6e20db63..96b8bb17dbff 100644 --- a/packages/webview_flutter/webview_flutter_web/example/README.md +++ b/packages/webview_flutter/webview_flutter_web/example/README.md @@ -1,3 +1,9 @@ -# webview_flutter_example +# Platform Implementation Test App -Demonstrates how to use the webview_flutter plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/packages/webview_flutter/webview_flutter_wkwebview/example/README.md b/packages/webview_flutter/webview_flutter_wkwebview/example/README.md index e5bd6e20db63..96b8bb17dbff 100644 --- a/packages/webview_flutter/webview_flutter_wkwebview/example/README.md +++ b/packages/webview_flutter/webview_flutter_wkwebview/example/README.md @@ -1,3 +1,9 @@ -# webview_flutter_example +# Platform Implementation Test App -Demonstrates how to use the webview_flutter plugin. +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. diff --git a/script/tool/CHANGELOG.md b/script/tool/CHANGELOG.md index 8dbb4840a672..f6dfb0e58266 100644 --- a/script/tool/CHANGELOG.md +++ b/script/tool/CHANGELOG.md @@ -1,3 +1,9 @@ +## NEXT + +* Adds `readme-check` validation that the example/README.md for a federated + plugin's implementation packages has a warning about the intended use of the + example instead of the template boilerplate. + ## 0.10.0 * Improves the logic in `version-check` to determine what changes don't require diff --git a/script/tool/lib/src/readme_check_command.dart b/script/tool/lib/src/readme_check_command.dart index 4acf997a0085..e3fbc7bc454d 100644 --- a/script/tool/lib/src/readme_check_command.dart +++ b/script/tool/lib/src/readme_check_command.dart @@ -104,11 +104,8 @@ class ReadmeCheckCommand extends PackageLoopingCommand { errors.add(blockValidationError); } - if (_containsTemplateBoilerplate(readmeLines)) { - printError('${indentation}The boilerplate section about getting started ' - 'with Flutter should not be left in.'); - errors.add('Contains template boilerplate'); - } + errors.addAll(_validateBoilerplate(readmeLines, + mainPackage: mainPackage, isExample: isExample)); // Check if this is the main readme for a plugin, and if so enforce extra // checks. @@ -284,10 +281,63 @@ ${indentation * 2}Please use standard capitalizations: ${sortedListString(expect return null; } - /// Returns true if the README still has the boilerplate from the - /// `flutter create` templates. - bool _containsTemplateBoilerplate(List readmeLines) { + /// Validates [readmeLines], outputing error messages for any issue and + /// returning an array of error summaries (if any). + /// + /// Returns an empty array if validation passes. + List _validateBoilerplate( + List readmeLines, { + required RepositoryPackage mainPackage, + required bool isExample, + }) { + final List errors = []; + + if (_containsTemplateFlutterBoilerplate(readmeLines)) { + printError('${indentation}The boilerplate section about getting started ' + 'with Flutter should not be left in.'); + errors.add('Contains template boilerplate'); + } + + // Enforce a repository-standard message in implementation plugin examples, + // since they aren't typical examples, which has been a source of + // confusion for plugin clients who find them. + if (isExample && mainPackage.isPlatformImplementation) { + if (_containsExampleBoilerplate(readmeLines)) { + printError('${indentation}The boilerplate should not be left in for a ' + "federated plugin implementation package's example."); + errors.add('Contains template boilerplate'); + } + if (!_containsImplementationExampleExplanation(readmeLines)) { + printError('${indentation}The example README for a platform ' + 'implementation package should warn readers about its intended ' + 'use. Please copy the example README from another implementation ' + 'package in this repository.'); + errors.add('Missing implementation package example warning'); + } + } + + return errors; + } + + /// Returns true if the README still has unwanted parts of the boilerplate + /// from the `flutter create` templates. + bool _containsTemplateFlutterBoilerplate(List readmeLines) { return readmeLines.any((String line) => line.contains('For help getting started with Flutter')); } + + /// Returns true if the README still has the generic description of an + /// example from the `flutter create` templates. + bool _containsExampleBoilerplate(List readmeLines) { + return readmeLines + .any((String line) => line.contains('Demonstrates how to use the')); + } + + /// Returns true if the README contains the repository-standard explanation of + /// the purpose of a federated plugin implementation's example. + bool _containsImplementationExampleExplanation(List readmeLines) { + return readmeLines.contains('# Platform Implementation Test App') && + readmeLines + .any((String line) => line.contains('This is a test app for')); + } } diff --git a/script/tool/test/readme_check_command_test.dart b/script/tool/test/readme_check_command_test.dart index 37224fddc56b..eb2b6c8e7512 100644 --- a/script/tool/test/readme_check_command_test.dart +++ b/script/tool/test/readme_check_command_test.dart @@ -176,6 +176,147 @@ samples, guidance on mobile development, and a full API reference. ); }); + test( + 'fails when a plugin implementation package example README has the ' + 'template boilerplate', () async { + final RepositoryPackage package = createFakePlugin( + 'a_plugin_ios', packagesDir.childDirectory('a_plugin')); + package.getExamples().first.readmeFile.writeAsStringSync(''' +# a_plugin_ios_example + +Demonstrates how to use the a_plugin_ios plugin. +'''); + + Error? commandError; + final List output = await runCapturingPrint( + runner, ['readme-check'], errorHandler: (Error e) { + commandError = e; + }); + + expect(commandError, isA()); + expect( + output, + containsAllInOrder([ + contains('The boilerplate should not be left in for a federated plugin ' + "implementation package's example."), + contains('Contains template boilerplate'), + ]), + ); + }); + + test( + 'allows the template boilerplate in the example README for packages ' + 'other than plugin implementation packages', () async { + final RepositoryPackage package = createFakePlugin( + 'a_plugin', + packagesDir.childDirectory('a_plugin'), + platformSupport: { + platformAndroid: const PlatformDetails(PlatformSupport.inline), + }, + ); + // Write a README with an OS support table so that the main README check + // passes. + package.readmeFile.writeAsStringSync(''' +# a_plugin + +| | Android | +|----------------|---------| +| **Support** | SDK 19+ | + +A great plugin. +'''); + package.getExamples().first.readmeFile.writeAsStringSync(''' +# a_plugin_example + +Demonstrates how to use the a_plugin plugin. +'''); + + final List output = + await runCapturingPrint(runner, ['readme-check']); + + expect( + output, + containsAll([ + contains(' Checking README.md...'), + contains(' Checking example/README.md...'), + ]), + ); + }); + + test( + 'fails when a plugin implementation package example README does not have ' + 'the repo-standard message', () async { + final RepositoryPackage package = createFakePlugin( + 'a_plugin_ios', packagesDir.childDirectory('a_plugin')); + package.getExamples().first.readmeFile.writeAsStringSync(''' +# a_plugin_ios_example + +Some random description. +'''); + + Error? commandError; + final List output = await runCapturingPrint( + runner, ['readme-check'], errorHandler: (Error e) { + commandError = e; + }); + + expect(commandError, isA()); + expect( + output, + containsAllInOrder([ + contains('The example README for a platform implementation package ' + 'should warn readers about its intended use. Please copy the ' + 'example README from another implementation package in this ' + 'repository.'), + contains('Missing implementation package example warning'), + ]), + ); + }); + + test('passes for a plugin implementation package with the expected content', + () async { + final RepositoryPackage package = createFakePlugin( + 'a_plugin', + packagesDir.childDirectory('a_plugin'), + platformSupport: { + platformAndroid: const PlatformDetails(PlatformSupport.inline), + }, + ); + // Write a README with an OS support table so that the main README check + // passes. + package.readmeFile.writeAsStringSync(''' +# a_plugin + +| | Android | +|----------------|---------| +| **Support** | SDK 19+ | + +A great plugin. +'''); + package.getExamples().first.readmeFile.writeAsStringSync(''' +# Platform Implementation Test App + +This is a test app for manual testing and automated integration testing +of this platform implementation. It is not intended to demonstrate actual use of +this package, since the intent is that plugin clients use the app-facing +package. + +Unless you are making changes to this implementation package, this example is +very unlikely to be relevant. +'''); + + final List output = + await runCapturingPrint(runner, ['readme-check']); + + expect( + output, + containsAll([ + contains(' Checking README.md...'), + contains(' Checking example/README.md...'), + ]), + ); + }); + test( 'fails when multi-example top-level example directory README still has ' 'application template boilerplate', () async {