In a Flutter federated plugin, why must platform implementations extend the PlatformInterface subclass rather than implement it, and how do tests still mock it?

## The problem the rule solves In a federated plugin, many packages — some written by people who never talk to each other — depend on one abstract class in the **platform-interface package**. That class will grow: a new feature means a new method. In Dart: - A class that **extends** an abstract class inherits every concrete method body. If the interface adds `Future<double> readHumidity() { throw UnimplementedError(); }`, subclasses still compile and simply inherit the throwing default. - A class that **implements** it must declare every member itself. Adding any method breaks every implementing class until its author catches up. So the ecosystem's rule is: **platform interfaces grow by adding methods with default bodies, and implementations must extend, never implement**. That keeps additions a minor, non-breaking release and lets platform packages adopt new methods at their own pace. ## How the rule is enforced The `plugin_platform_interface` package turns the convention into a runtime check: ```dart abstract class ThermoPlatform extends PlatformInterface { ThermoPlatform() : super(token: _token); static final Object _token = Object(); static ThermoPlatform _instance = MethodChannelThermo(); static ThermoPlatform get instance => _instance; static set instance(ThermoPlatform instance) { PlatformInterface.verify(instance, _token); _instance = instance; } Future<double> readCelsius() { throw UnimplementedError('readCelsius() has not been implemented.'); } } ``` 1. The constructor hands a **private token** to `PlatformInterface`, which remembers it for that object (in an `Expando`). 2. Only code that runs this constructor — a subclass using `extends` — produces an object carrying the right token. 3. The `instance` setter calls `verify`. If the tokens do not match, it throws an `AssertionError` saying platform interfaces must not be implemented with `implements`. The check is an explicit `throw`, not an `assert`, so it applies in release builds too. | Method | Checks the token | Rejects `const Object()` as the token | |---|---|---| | `PlatformInterface.verify` | Yes | Yes | | `PlatformInterface.verifyToken` | Yes | No — documented as to be deprecated | `flutter create --template=plugin` still generates `verifyToken`; new interfaces can use `verify`. The token must be a fresh `Object()`, because every `const Object()` is the same canonical instance and would let any class forge it. ## Testing: mocks and fakes A mockito `Mock` or a `Fake` is usually written with `implements`, so it would fail verification. The package provides **`MockPlatformInterfaceMixin`**: ```dart class FakeThermoPlatform extends Fake with MockPlatformInterfaceMixin implements ThermoPlatform { @override Future<double> readCelsius() async => 21.5; } void main() { test('reads temperature', () async { ThermoPlatform.instance = FakeThermoPlatform(); expect(await Thermo().readCelsius(), 21.5); }); } ``` - Objects with the mixin pass `verify` **only when assertions are enabled** (tests and debug builds). - In a release build the mixin makes `verify` throw, so a test double can never ship as the real implementation. ## What this means for plugin maintainers - Add methods to the interface with bodies that `throw UnimplementedError('readHumidity() has not been implemented.')`. That is a minor version. - Removing or changing a method's signature is still breaking and forces every platform package to update — the most expensive change in a federated plugin, so it is avoided or batched. - Platform packages keep the default for methods their platform cannot support; the app-facing package can document or detect that. - Do not reach for `implements` to "decouple" an implementation; it trades a compile-time convenience for a runtime failure the first time the app sets `instance`. ## Common misunderstandings - The check is not a lint; it is enforced when `instance` is assigned. - `extends` does not mean implementations share state with the interface; each registers its own object. - The mixin is not a production escape hatch.