Improve documentation with an FAQ.
Addresses comments in https://github.com/dart-lang/mockito/issues/245, https://github.com/dart-lang/mockito/issues/247, and https://github.com/dart-lang/mockito/issues/239
PiperOrigin-RevId: 307714765
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cfe10bc..9d485e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
clients who use the Mock class in unconventional ways, such as overriding
`noSuchMethod` on a class which extends Mock. To fix, or prepare such code,
add a second parameter to such overriding `noSuchMethod` declaration.
+* Increase minimum Dart SDK to `2.4.0`.
## 4.1.1
diff --git a/README.md b/README.md
index 09b6878..61a09dd 100644
--- a/README.md
+++ b/README.md
@@ -243,7 +243,7 @@
```dart
// Simple capture
cat.eatFood("Fish");
-expect(verify(cat.eatFood(captureAny)).captured.single, "Fish");
+expect(verify(cat.eatFood(captureAny)).captured.single, ["Fish"]);
// Capture multiple calls
cat.eatFood("Milk");
@@ -349,70 +349,9 @@
lead to confusion. It is OK to define _static_ utilities on a class which
`extends Mock` if it helps with code structure.
+## Frequently asked questions
-## How it works
-
-The basics of the `Mock` class are nothing special: It uses `noSuchMethod` to
-catch all method invocations, and returns the value that you have configured
-beforehand with `when()` calls.
-
-The implementation of `when()` is a bit more tricky. Take this example:
-
-```dart
-// Unstubbed methods return null:
-expect(cat.sound(), nullValue);
-
-// Stubbing - before execution:
-when(cat.sound()).thenReturn("Purr");
-```
-
-Since `cat.sound()` returns `null`, how can the `when()` call configure it?
-
-It works, because `when` is not a function, but a top level getter that
-_returns_ a function. Before returning the function, it sets a flag
-(`_whenInProgress`), so that all `Mock` objects know to return a "matcher"
-(internally `_WhenCall`) instead of the expected value. As soon as the function
-has been invoked `_whenInProgress` is set back to `false` and Mock objects
-behave as normal.
-
-Argument matchers work by storing the wrapped arguments, one after another,
-until the `when` (or `verify`) call gathers everything that has been stored,
-and creates an InvocationMatcher with the arguments. This is a simple process
-for positional arguments: the order in which the arguments has been stored
-should be preserved for matching an invocation. Named arguments are trickier:
-their evaluation order is not specified, so if Mockito blindly stored them in
-the order of their evaluation, it wouldn't be able to match up each argument
-matcher with the correct name. This is why each named argument matcher must
-repeat its own name. `foo: anyNamed('foo')` tells Mockito to store an argument
-matcher for an invocation under the name 'foo'.
-
-> **Be careful** never to write `when;` (without the function call) anywhere.
-> This would set `_whenInProgress` to `true`, and the next mock invocation will
-> return an unexpected value.
-
-The same goes for "chaining" mock objects in a test call. This will fail:
-
-```dart
-var mockUtils = MockUtils();
-var mockStringUtils = MockStringUtils();
-
-// Setting up mockUtils.stringUtils to return a mock StringUtils implementation
-when(mockUtils.stringUtils).thenReturn(mockStringUtils);
-
-// Some tests
-
-// FAILS!
-verify(mockUtils.stringUtils.uppercase()).called(1);
-// Instead use this:
-verify(mockStringUtils.uppercase()).called(1);
-```
-
-This fails, because `verify` sets an internal flag, so mock objects don't
-return their mocked values anymore but their matchers. So
-`mockUtils.stringUtils` will *not* return the mocked `stringUtils` object you
-put inside.
-
-You can look at the `when` and `Mock.noSuchMethod` implementations to see how
-it's done. It's very straightforward.
+Read more information about this package in the
+[FAQ](https://github.com/dart-lang/mockito/blob/master/FAQ.md).
**NOTE:** This is not an official Google product
diff --git a/lib/src/mock.dart b/lib/src/mock.dart
index 5d5afc4..241ad2e 100644
--- a/lib/src/mock.dart
+++ b/lib/src/mock.dart
@@ -930,6 +930,10 @@
/// verify(cat.eatFood("fish")).called(greaterThan(3));
/// ```
///
+/// Note: When mockito verifies a method call, said call is then excluded from
+/// further verifications. A single method call cannot be verified from multiple
+/// calls to `verify`, or `verifyInOrder`. See more details in the FAQ.
+///
/// Note: because of an unintended limitation, `verify(...).called(0);` will
/// not work as expected. Please use `verifyNever(...);` instead.
///
diff --git a/pubspec.yaml b/pubspec.yaml
index e76d7aa..f89993c 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,15 +1,11 @@
name: mockito
version: 4.1.2-dev
-authors:
- - Dmitriy Fibulwinter <fibulwinter@gmail.com>
- - Dart Team <misc@dartlang.org>
-
description: A mock framework inspired by Mockito.
homepage: https://github.com/dart-lang/mockito
environment:
- sdk: '>=2.3.0 <3.0.0'
+ sdk: '>=2.4.0 <3.0.0'
dependencies:
analyzer: ^0.38.0
