more setTextEntryEmulation docs; isRegistered check (#13420)

packages/flutter_driver/lib/src/driver/driver.dart

@@ -435,6 +435,9 @@ class FlutterDriver {
   /// calling this method. Typically, a test would activate a widget, e.g. using
   /// [tap], then call this method.
   ///
+  /// For this method to work, text emulation must be enabled (see
+  /// [setTextEntryEmulation]). Text emulation is enabled by default.
+  ///
   /// Example:
   ///
   /// ```dart
@@ -452,9 +455,17 @@ class FlutterDriver {
   }
 
   /// If `enabled` is true, enables text entry emulation via [enterText]. If
-  /// `enabled` is false, disables it.
+  /// `enabled` is false, disables it. By default text entry emulation is
+  /// enabled.
+  ///
+  /// When disabled, [enterText] will fail with a [DriverError]. When an
+  /// [EditableText] is focused, the operating system's configured keyboard
+  /// method is invoked, such as an on-screen keyboard on a phone or a tablet.
   ///
-  /// By default text entry emulation is enabled.
+  /// When enabled, the operating system's configured keyboard will not be
+  /// invoked when the widget is focused, as the [SystemChannels.textInput]
+  /// channel will be mocked out. In disabled mode [enterText] can be used to
+  /// emulate text entry.
   Future<Null> setTextEntryEmulation({ @required bool enabled, Duration timeout }) async {
     assert(enabled != null);
     await _sendCommand(new SetTextEntryEmulation(enabled, timeout: timeout));

packages/flutter_driver/lib/src/extension/extension.dart

@@ -345,6 +345,10 @@ class FlutterDriverExtension {
   }
 
   Future<EnterTextResult> _enterText(Command command) async {
+    if (!_testTextInput.isRegistered) {
+      throw 'Unable to fulfill `FlutterDriver.enterText`. Text emulation is '
+            'disabled. You can enable it using `FlutterDriver.setTextEntryEmulation`.';
+    }
     final EnterText enterTextCommand = command;
     _testTextInput.enterText(enterTextCommand.text);
     return new EnterTextResult();

packages/flutter_test/lib/src/test_text_input.dart

@@ -22,6 +22,7 @@ class TestTextInput {
   /// Installs this object as a mock handler for [SystemChannels.textInput].
   void register() {
     SystemChannels.textInput.setMockMethodCallHandler(_handleTextInputCall);
+    _isRegistered = true;
   }
 
   /// Removes this object as a mock handler for [SystemChannels.textInput].
@@ -31,8 +32,15 @@ class TestTextInput {
   /// on-screen keyboard provided by the operating system.
   void unregister() {
     SystemChannels.textInput.setMockMethodCallHandler(null);
+    _isRegistered = false;
   }
 
+  /// Whether this [TestTextInput] is registered with [SystemChannels.textInput].
+  ///
+  /// Use [register] and [unregister] methods to control this value.
+  bool get isRegistered => _isRegistered;
+  bool _isRegistered = false;
+
   int _client = 0;
 
   /// Arguments supplied to the TextInput.setClient method call.