Add docs and sample for takeException (#27140)

* Add docs and sample for takeException

* fix sample

packages/flutter_test/lib/src/matchers.dart

@@ -155,6 +155,9 @@ const Matcher hasAGoodToStringDeep = _HasGoodToStringDeep();
 ///
 /// This is equivalent to `throwsA(isInstanceOf<FlutterError>())`.
 ///
+/// If you are trying to test whether a call to [WidgetTester.pumpWidget]
+/// results in a [FlutterError], see [TestWidgetsFlutterBinding.takeException].
+///
 /// See also:
 ///
 ///  * [throwsAssertionError], to test if a function throws any [AssertionError].
@@ -166,6 +169,10 @@ final Matcher throwsFlutterError = throwsA(isFlutterError);
 ///
 /// This is equivalent to `throwsA(isInstanceOf<AssertionError>())`.
 ///
+/// If you are trying to test whether a call to [WidgetTester.pumpWidget]
+/// results in an [AssertionError], see
+/// [TestWidgetsFlutterBinding.takeException].
+///
 /// See also:
 ///
 ///  * [throwsFlutterError], to test if a function throws a [FlutterError].

packages/flutter_test/lib/src/widget_tester.dart

@@ -225,6 +225,19 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
   /// rebuild of the tree, even if [widget] is the same as the previous call.
   /// [pump] will only rebuild the widgets that have changed.
   ///
+  /// This method should not be used as the first parameter to an [expect] or
+  /// [expectLater] call to test that a widget throws an exception. Instead, use
+  /// [TestWidgetsFlutterBinding.takeException].
+  ///
+  /// {@tool sample}
+  /// ```dart
+  /// testWidgets('MyWidget asserts invalid bounds', (WidgetTester tester) async {
+  ///   await tester.pumpWidget(MyWidget(-1));
+  ///   expect(tester.takeException(), isAssertionError); // or isNull, as appropriate.
+  /// });
+  /// ```
+  /// {@end-tool}
+  ///
   /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
   /// this method works when the test is run with `flutter run`.
   Future<void> pumpWidget(Widget widget, [