[integration_test] Recommend tests to be in integration_test/, fix example

.cirrus.yml

@@ -59,7 +59,7 @@ task:
         - ./chromedriver/chromedriver --port=4444 &
       test_script:
         - cd $INTEGRATION_TEST_PATH/example/
-        - flutter drive -v --target=test_driver/example_integration.dart -d web-server --release --browser-name=chrome
+        - flutter drive -v --driver=test_driver/integration_test_driver.dart --target=integration_test/example_test.dart -d web-server --release --browser-name=chrome
     - name: build-apks+java-test+firebase-test-lab
       env:
         matrix:

packages/integration_test/README.md

@@ -7,78 +7,91 @@ and native Android instrumentation testing.
 ## Usage
 
 Add a dependency on the `integration_test` and `flutter_test` package in the
-`dev_dependencies` section of pubspec.yaml. For plugins, do this in the
-pubspec.yaml of the example app.
+`dev_dependencies` section of `pubspec.yaml`. For plugins, do this in the
+`pubspec.yaml` of the example app.
 
-Invoke `IntegrationTestWidgetsFlutterBinding.ensureInitialized()` at the start
-of a test file, e.g.
+Create a `integration_test/` directory for your package. In this directory,
+create a `<name>_test.dart`, using the following as a starting point to make
+assertions.
 
 ```dart
 import 'package:flutter_test/flutter_test.dart';
 import 'package:integration_test/integration_test.dart';
 
 void main() {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
   testWidgets("failing test example", (WidgetTester tester) async {
     expect(2 + 2, equals(5));
   });
 }
 ```
 
-## Test locations
-
-It is recommended to put integration_test tests in the `test/` folder of the app
-or package. For example apps, if the integration_test test references example
-app code, it should go in `example/test/`. It is also acceptable to put
-integration_test tests in `test_driver/` folder so that they're alongside the
-runner app (see below).
-
-## Using Flutter Driver to Run Tests
-
-`IntegrationTestWidgetsTestBinding` supports launching the on-device tests with
-`flutter drive`. Note that the tests don't use the `FlutterDriver` API, they
-use `testWidgets` instead.
+### Driver Entrypoint
 
-Put the a file named `<package_name>_integration_test.dart` in the app'
-`test_driver` directory:
+An accompanying driver script will be needed that can be shared across all
+integration tests. Create a `integration_test_driver.dart` in the `test_driver/`
+directory with the following contents:
 
 ```dart
-import 'dart:async';
-
 import 'package:integration_test/integration_test_driver.dart';
 
-Future<void> main() async => integrationDriver();
+Future<void> main() => integrationDriver();
 ```
 
-To run a example app test with Flutter driver:
+### Package Structure
+
+Your package should have a structure that looks like this:
 
-```sh
-cd example
-flutter drive test/<package_name>_integration.dart
+```
+lib/
+  ...
+integration_test/
+  foo_test.dart
+  bar_test.dart
+test/
+  # Other unit tests go here.
+test_driver/
+  integration_test_driver.dart
 ```
 
-To test plugin APIs using Flutter driver:
+[Example](https://github.com/flutter/plugins/tree/master/packages/integration_test/example)
+
+## Using Flutter Driver to Run Tests
+
+These tests can be launched with the `flutter drive` command.
+
+To run `integration_test/foo_test.dart`:
 
 ```sh
-cd example
-flutter drive --driver=test_driver/<package_name>_test.dart test/<package_name>_integration_test.dart
+flutter drive \
+  --driver=test_driver/integration_test_driver.dart \
+  --target=integration_test/foo_test.dart
 ```
 
-You can run tests on web in release or profile mode.
+### Web
+
+Make sure you have [enabled web support](https://flutter.dev/docs/get-started/web#set-up)
+then [download and run](https://flutter.dev/docs/cookbook/testing/integration/introduction#6b-web)
+the web driver in another process.
 
-First you need to make sure you have downloaded the driver for the browser.
+Use following command to execute the tests, passing either `--release` or
+`--profile` as debug mode is not supported.
 
 ```sh
-cd example
-flutter drive -v --target=test_driver/<package_name>dart -d web-server --release --browser-name=chrome
+flutter drive \
+  --driver=test_driver/integration_test_driver.dart \
+  --target=integration_test/foo_test.dart \
+  -d web-server \
+  --release
 ```
 
-## Android device testing
+## Android Device Testing
 
 Create an instrumentation test file in your application's
 **android/app/src/androidTest/java/com/example/myapp/** directory (replacing
 com, example, and myapp with values from your app's package name). You can name
-this test file MainActivityTest.java or another name of your choice.
+this test file `MainActivityTest.java` or another name of your choice.
 
 ```java
 package com.example.myapp;
@@ -96,7 +109,7 @@ public class MainActivityTest {
 ```
 
 Update your application's **myapp/android/app/build.gradle** to make sure it
-uses androidx's version of AndroidJUnitRunner and has androidx libraries as a
+uses androidx's version of `AndroidJUnitRunner` and has androidx libraries as a
 dependency.
 
 ```gradle
@@ -160,7 +173,7 @@ You can pass additional parameters on the command line, such as the
 devices you want to test on. See
 [gcloud firebase test android run](https://cloud.google.com/sdk/gcloud/reference/firebase/test/android/run).
 
-## iOS device testing
+## iOS Device Testing
 
 You need to change `iOS/Podfile` to avoid test target statically linking to the plugins. One way is to
 link all of the plugins dynamically:
@@ -189,4 +202,4 @@ change the code. You can change `RunnerTests.m` to the name of your choice.
 INTEGRATION_TEST_IOS_RUNNER(RunnerTests)
 ```
 
-Now you can start RunnerTests to kick out integration tests!
+Now you can start RunnerTests to kick-off integration tests!

packages/integration_test/example/README.md

@@ -2,15 +2,22 @@
 
 Demonstrates how to use the `package:integration_test`.
 
-## Getting Started
+To run `integration_test/example_test.dart`,
 
-This project is a starting point for a Flutter application.
+Android / iOS:
 
-A few resources to get you started if this is your first Flutter project:
+```sh
+flutter drive \
+  --driver=test_driver/integration_test_driver.dart \
+  --target=integration_test/example_test.dart
+```
 
-- [Lab: Write your first Flutter app](https://flutter.dev/docs/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://flutter.dev/docs/cookbook)
+Web:
 
-For help getting started with Flutter, view our
-[online documentation](https://flutter.dev/docs), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+```sh
+flutter drive \
+  --driver=test_driver/integration_test_driver.dart \
+  --target=integration_test/example_test.dart \
+  -d web-server \
+  --release
+```

packages/integration_test/example/test_driver/example_integration.dart → packages/integration_test/example/integration_test/example_test.dart

@@ -7,8 +7,8 @@
 
 import 'package:integration_test/integration_test.dart';
 
-import 'example_integration_io.dart'
-    if (dart.library.html) 'example_integration_web.dart' as tests;
+import '_example_test_io.dart' if (dart.library.html) '_example_test_web.dart'
+    as tests;
 
 void main() {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();

packages/integration_test/example/test_driver/example_integration_extended.dart → packages/integration_test/example/integration_test/extended_test.dart

@@ -1,6 +1,7 @@
 // This is a Flutter widget test can take a screenshot.
 //
-// NOTE: Screenshots are only supported on Web for now.
+// NOTE: Screenshots are only supported on Web for now. For Web, this needs to
+// be executed with the `test_driver/integration_test_extended_driver.dart`.
 //
 // To perform an interaction with a widget in your test, use the WidgetTester
 // utility that Flutter provides. For example, you can send tap and scroll
@@ -9,8 +10,8 @@
 
 import 'package:integration_test/integration_test.dart';
 
-import 'example_integration_io_extended.dart'
-    if (dart.library.html) 'example_integration_web_extended.dart' as tests;
+import '_extended_test_io.dart' if (dart.library.html) '_extended_test_web.dart'
+    as tests;
 
 void main() {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();

packages/integration_test/example/test_driver/integration_test_driver.dart

@@ -0,0 +1,3 @@
+import 'package:integration_test/integration_test_driver.dart';
+
+Future<void> main() => integrationDriver();

packages/integration_test/example/test_driver/example_integration_extended_test.dart → packages/integration_test/example/test_driver/integration_test_extended_driver.dart

@@ -1,5 +1,3 @@
-import 'dart:async';
-
 import 'package:flutter_driver/flutter_driver.dart';
 import 'package:integration_test/integration_test_driver_extended.dart';
 

packages/integration_test/example/test_driver/failure_test.dart → packages/integration_test/example/test_driver/integration_test_failure_driver.dart

@@ -1,7 +1,5 @@
-import 'dart:async';
-
-import 'package:integration_test/common.dart' as common;
 import 'package:flutter_driver/flutter_driver.dart';
+import 'package:integration_test/common.dart' as common;
 import 'package:test/test.dart';
 
 Future<void> main() async {