find.dart 14.6 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6
import 'dart:convert';

7 8
import 'package:meta/meta.dart';

9
import 'deserialization_factory.dart';
10 11 12
import 'error.dart';
import 'message.dart';

13
const List<Type> _supportedKeyValueTypes = <Type>[String, int];
14

15
DriverError _createInvalidKeyValueTypeError(String invalidType) {
16
  return DriverError('Unsupported key value type $invalidType. Flutter Driver only supports ${_supportedKeyValueTypes.join(", ")}');
17 18
}

19
/// A Flutter Driver command aimed at an object to be located by [finder].
20 21 22 23 24
///
/// Implementations must provide a concrete [kind]. If additional data is
/// required beyond the [finder] the implementation may override [serialize]
/// and add more keys to the returned map.
abstract class CommandWithTarget extends Command {
25
  /// Constructs this command given a [finder].
26
  CommandWithTarget(this.finder, {Duration? timeout}) : super(timeout: timeout) {
27
    assert(finder != null, '$runtimeType target cannot be null');
28 29
  }

30
  /// Deserializes this command from the value generated by [serialize].
31 32
  CommandWithTarget.deserialize(Map<String, String> json, DeserializeFinderFactory finderFactory)
    : finder = finderFactory.deserializeFinder(json),
33
      super.deserialize(json);
34

35 36 37 38 39 40 41 42 43 44 45
  /// Locates the object or objects targeted by this command.
  final SerializableFinder finder;

  /// This method is meant to be overridden if data in addition to [finder]
  /// is serialized to JSON.
  ///
  /// Example:
  ///
  ///     Map<String, String> toJson() => super.toJson()..addAll({
  ///       'foo': this.foo,
  ///     });
46
  @override
47 48
  Map<String, String> serialize() =>
      super.serialize()..addAll(finder.serialize());
49 50
}

51
/// A Flutter Driver command that waits until [finder] can locate the target.
52
class WaitFor extends CommandWithTarget {
53 54 55
  /// Creates a command that waits for the widget identified by [finder] to
  /// appear within the [timeout] amount of time.
  ///
56
  /// If [timeout] is not specified, the command defaults to no timeout.
57
  WaitFor(SerializableFinder finder, {Duration? timeout})
58
    : super(finder, timeout: timeout);
59

60
  /// Deserializes this command from the value generated by [serialize].
61
  WaitFor.deserialize(Map<String, String> json, DeserializeFinderFactory finderFactory) : super.deserialize(json, finderFactory);
62 63

  @override
64
  String get kind => 'waitFor';
65
}
66

67 68
/// A Flutter Driver command that waits until [finder] can no longer locate the target.
class WaitForAbsent extends CommandWithTarget {
69 70 71
  /// Creates a command that waits for the widget identified by [finder] to
  /// disappear within the [timeout] amount of time.
  ///
72
  /// If [timeout] is not specified, the command defaults to no timeout.
73
  WaitForAbsent(SerializableFinder finder, {Duration? timeout})
74
    : super(finder, timeout: timeout);
75

76
  /// Deserializes this command from the value generated by [serialize].
77
  WaitForAbsent.deserialize(Map<String, String> json, DeserializeFinderFactory finderFactory) : super.deserialize(json, finderFactory);
78

79
  @override
80
  String get kind => 'waitForAbsent';
81 82
}

83 84 85
/// A Flutter Driver command that waits until [finder] can be tapped.
class WaitForTappable extends CommandWithTarget {
  /// Creates a command that waits for the widget identified by [finder] to
86
  /// be tappable within the [timeout] amount of time.
87
  ///
88
  /// If [timeout] is not specified, the command defaults to no timeout.
89 90 91 92 93 94 95 96 97 98 99 100
  WaitForTappable(SerializableFinder finder, {Duration? timeout})
      : super(finder, timeout: timeout);

  /// Deserialized this command from the value generated by [serialize].
  WaitForTappable.deserialize(
      Map<String, String> json, DeserializeFinderFactory finderFactory)
      : super.deserialize(json, finderFactory);

  @override
  String get kind => 'waitForTappable';
}

101 102
/// Base class for Flutter Driver finders, objects that describe how the driver
/// should search for elements.
103
abstract class SerializableFinder {
104 105 106 107

  /// A const constructor to allow subclasses to be const.
  const SerializableFinder();

108
  /// Identifies the type of finder to be used by the driver extension.
109
  String get finderType;
110

111 112 113 114 115 116 117 118
  /// Serializes common fields to JSON.
  ///
  /// Methods that override [serialize] are expected to call `super.serialize`
  /// and add more fields to the returned [Map].
  @mustCallSuper
  Map<String, String> serialize() => <String, String>{
    'finderType': finderType,
  };
119 120
}

121
/// A Flutter Driver finder that finds widgets by tooltip text.
122
class ByTooltipMessage extends SerializableFinder {
123
  /// Creates a tooltip finder given the tooltip's message [text].
124
  const ByTooltipMessage(this.text);
125 126 127 128

  /// Tooltip message text.
  final String text;

129
  @override
130
  String get finderType => 'ByTooltipMessage';
131

132
  @override
pq's avatar
pq committed
133
  Map<String, String> serialize() => super.serialize()..addAll(<String, String>{
134 135 136
    'text': text,
  });

137
  /// Deserializes the finder from JSON generated by [serialize].
138
  static ByTooltipMessage deserialize(Map<String, String> json) {
139
    return ByTooltipMessage(json['text']!);
140 141 142
  }
}

143 144 145 146 147 148
/// A Flutter Driver finder that finds widgets by semantic label.
///
/// If the [label] property is a [String], the finder will try to find an exact
/// match. If it is a [RegExp], it will return true for [RegExp.hasMatch].
class BySemanticsLabel extends SerializableFinder {
  /// Creates a semantic label finder given the [label].
149
  const BySemanticsLabel(this.label);
150

151
  /// A [Pattern] matching the label of a [SemanticsNode].
152 153 154 155 156
  ///
  /// If this is a [String], it will be treated as an exact match.
  final Pattern label;

  @override
157
  String get finderType => 'BySemanticsLabel';
158 159 160 161

  @override
  Map<String, String> serialize() {
    if (label is RegExp) {
162
      final RegExp regExp = label as RegExp;
163 164 165 166 167 168
      return super.serialize()..addAll(<String, String>{
        'label': regExp.pattern,
        'isRegExp': 'true',
      });
    } else {
      return super.serialize()..addAll(<String, String>{
169
        'label': label as String,
170 171 172 173 174 175 176
      });
    }
  }

  /// Deserializes the finder from JSON generated by [serialize].
  static BySemanticsLabel deserialize(Map<String, String> json) {
    final bool isRegExp = json['isRegExp'] == 'true';
177
    return BySemanticsLabel(isRegExp ? RegExp(json['label']!) : json['label']!);
178 179 180
  }
}

Janice Collins's avatar
Janice Collins committed
181 182
/// A Flutter Driver finder that finds widgets by [text] inside a
/// [widgets.Text] or [widgets.EditableText] widget.
183
class ByText extends SerializableFinder {
184
  /// Creates a text finder given the text.
185
  const ByText(this.text);
186

Janice Collins's avatar
Janice Collins committed
187 188
  /// The text that appears inside the [widgets.Text] or [widgets.EditableText]
  /// widget.
189 190
  final String text;

191
  @override
192
  String get finderType => 'ByText';
193

194
  @override
pq's avatar
pq committed
195
  Map<String, String> serialize() => super.serialize()..addAll(<String, String>{
196 197 198
    'text': text,
  });

199
  /// Deserializes the finder from JSON generated by [serialize].
200
  static ByText deserialize(Map<String, String> json) {
201
    return ByText(json['text']!);
202 203 204
  }
}

205
/// A Flutter Driver finder that finds widgets by `ValueKey`.
206
class ByValueKey extends SerializableFinder {
207
  /// Creates a finder given the key value.
208
  ByValueKey(this.keyValue)
209 210
      : keyValueString = '$keyValue',
        keyValueType = '${keyValue.runtimeType}' {
211
    if (!_supportedKeyValueTypes.contains(keyValue.runtimeType))
212
      throw _createInvalidKeyValueTypeError('$keyValue.runtimeType');
213 214 215 216 217 218 219 220 221 222 223 224 225
  }

  /// The true value of the key.
  final dynamic keyValue;

  /// Stringified value of the key (we can only send strings to the VM service)
  final String keyValueString;

  /// The type name of the key.
  ///
  /// May be one of "String", "int". The list of supported types may change.
  final String keyValueType;

226
  @override
227
  String get finderType => 'ByValueKey';
228

229
  @override
pq's avatar
pq committed
230
  Map<String, String> serialize() => super.serialize()..addAll(<String, String>{
231 232
    'keyValueString': keyValueString,
    'keyValueType': keyValueType,
233
  });
234

235
  /// Deserializes the finder from JSON generated by [serialize].
236
  static ByValueKey deserialize(Map<String, String> json) {
237 238
    final String keyValueString = json['keyValueString']!;
    final String keyValueType = json['keyValueType']!;
239
    switch (keyValueType) {
240
      case 'int':
241
        return ByValueKey(int.parse(keyValueString));
242
      case 'String':
243
        return ByValueKey(keyValueString);
244
      default:
245
        throw _createInvalidKeyValueTypeError(keyValueType);
246 247 248 249
    }
  }
}

250
/// A Flutter Driver finder that finds widgets by their [runtimeType].
251
class ByType extends SerializableFinder {
252
  /// Creates a finder given the runtime type in string form.
253
  const ByType(this.type);
254 255 256 257

  /// The widget's [runtimeType], in string form.
  final String type;

258
  @override
259
  String get finderType => 'ByType';
260

261 262 263 264 265 266 267
  @override
  Map<String, String> serialize() => super.serialize()..addAll(<String, String>{
    'type': type,
  });

  /// Deserializes the finder from JSON generated by [serialize].
  static ByType deserialize(Map<String, String> json) {
268
    return ByType(json['type']!);
269 270
  }
}
271

272 273 274 275 276 277 278
/// A Flutter Driver finder that finds the back button on the page's Material
/// or Cupertino scaffold.
///
/// See also:
///
///  * [WidgetTester.pageBack], for a similar functionality in widget tests.
class PageBack extends SerializableFinder {
279 280 281
  /// Creates a [PageBack].
  const PageBack();

282 283 284 285
  @override
  String get finderType => 'PageBack';
}

286 287 288 289 290 291 292 293
/// A Flutter Driver finder that finds a descendant of [of] that matches
/// [matching].
///
/// If the `matchRoot` argument is true, then the widget specified by [of] will
/// be considered for a match. The argument defaults to false.
class Descendant extends SerializableFinder {
  /// Creates a descendant finder.
  const Descendant({
294 295
    required this.of,
    required this.matching,
296
    this.matchRoot = false,
297
    this.firstMatchOnly = false,
298 299 300 301 302 303 304 305 306 307 308
  });

  /// The finder specifying the widget of which the descendant is to be found.
  final SerializableFinder of;

  /// Only a descendant of [of] matching this finder will be found.
  final SerializableFinder matching;

  /// Whether the widget matching [of] will be considered for a match.
  final bool matchRoot;

309 310 311
  /// If true then only the first descendant matching `matching` will be returned.
  final bool firstMatchOnly;

312 313 314 315 316 317 318
  @override
  String get finderType => 'Descendant';

  @override
  Map<String, String> serialize() {
    return super.serialize()
        ..addAll(<String, String>{
319 320
          'of': jsonEncode(of.serialize()),
          'matching': jsonEncode(matching.serialize()),
321
          'matchRoot': matchRoot ? 'true' : 'false',
322
          'firstMatchOnly': firstMatchOnly ? 'true' : 'false',
323 324 325 326
        });
  }

  /// Deserializes the finder from JSON generated by [serialize].
327
  static Descendant deserialize(Map<String, String> json, DeserializeFinderFactory finderFactory) {
328
    final Map<String, String> jsonOfMatcher =
329
        Map<String, String>.from(jsonDecode(json['of']!) as Map<String, dynamic>);
330
    final Map<String, String> jsonMatchingMatcher =
331
        Map<String, String>.from(jsonDecode(json['matching']!) as Map<String, dynamic>);
332
    return Descendant(
333 334
      of: finderFactory.deserializeFinder(jsonOfMatcher),
      matching: finderFactory.deserializeFinder(jsonMatchingMatcher),
335 336
      matchRoot: json['matchRoot'] == 'true',
      firstMatchOnly: json['firstMatchOnly'] == 'true',
337 338 339 340 341 342 343 344 345 346 347 348
    );
  }
}

/// A Flutter Driver finder that finds an ancestor of [of] that matches
/// [matching].
///
/// If the `matchRoot` argument is true, then the widget specified by [of] will
/// be considered for a match. The argument defaults to false.
class Ancestor extends SerializableFinder {
  /// Creates an ancestor finder.
  const Ancestor({
349 350
    required this.of,
    required this.matching,
351
    this.matchRoot = false,
352
    this.firstMatchOnly = false,
353 354 355 356 357 358 359 360 361 362 363
  });

  /// The finder specifying the widget of which the ancestor is to be found.
  final SerializableFinder of;

  /// Only an ancestor of [of] matching this finder will be found.
  final SerializableFinder matching;

  /// Whether the widget matching [of] will be considered for a match.
  final bool matchRoot;

364 365 366
  /// If true then only the first ancestor matching `matching` will be returned.
  final bool firstMatchOnly;

367 368 369 370 371 372 373
  @override
  String get finderType => 'Ancestor';

  @override
  Map<String, String> serialize() {
    return super.serialize()
      ..addAll(<String, String>{
374 375
        'of': jsonEncode(of.serialize()),
        'matching': jsonEncode(matching.serialize()),
376
        'matchRoot': matchRoot ? 'true' : 'false',
377
        'firstMatchOnly': firstMatchOnly ? 'true' : 'false',
378 379 380 381
      });
  }

  /// Deserializes the finder from JSON generated by [serialize].
382
  static Ancestor deserialize(Map<String, String> json, DeserializeFinderFactory finderFactory) {
383
    final Map<String, String> jsonOfMatcher =
384
        Map<String, String>.from(jsonDecode(json['of']!) as Map<String, dynamic>);
385
    final Map<String, String> jsonMatchingMatcher =
386
        Map<String, String>.from(jsonDecode(json['matching']!) as Map<String, dynamic>);
387
    return Ancestor(
388 389
      of: finderFactory.deserializeFinder(jsonOfMatcher),
      matching: finderFactory.deserializeFinder(jsonMatchingMatcher),
390 391
      matchRoot: json['matchRoot'] == 'true',
      firstMatchOnly: json['firstMatchOnly'] == 'true',
392 393 394 395
    );
  }
}

396 397 398 399 400 401
/// A Flutter driver command that retrieves a semantics id using a specified finder.
///
/// This command requires assertions to be enabled on the device.
///
/// If the object returned by the finder does not have its own semantics node,
/// then the semantics node of the first ancestor is returned instead.
402
///
403 404 405 406 407 408 409 410
/// Throws an error if a finder returns multiple objects or if there are no
/// semantics nodes.
///
/// Semantics must be enabled to use this method, either using a platform
/// specific shell command or [FlutterDriver.setSemantics].
class GetSemanticsId extends CommandWithTarget {

  /// Creates a command which finds a Widget and then looks up the semantic id.
411
  GetSemanticsId(SerializableFinder finder, {Duration? timeout}) : super(finder, timeout: timeout);
412

413
  /// Creates a command from a JSON map.
414 415
  GetSemanticsId.deserialize(Map<String, String> json, DeserializeFinderFactory finderFactory)
    : super.deserialize(json, finderFactory);
416 417 418 419 420 421 422 423 424

  @override
  String get kind => 'get_semantics_id';
}

/// The result of a [GetSemanticsId] command.
class GetSemanticsIdResult extends Result {

  /// Creates a new [GetSemanticsId] result.
425
  const GetSemanticsIdResult(this.id);
426

427
  /// The semantics id of the node.
428 429 430 431
  final int id;

  /// Deserializes this result from JSON.
  static GetSemanticsIdResult fromJson(Map<String, dynamic> json) {
432
    return GetSemanticsIdResult(json['id'] as int);
433 434 435 436 437
  }

  @override
  Map<String, dynamic> toJson() => <String, dynamic>{'id': id};
}