[pigeon] Deprecate dartHostTestHandler (#10403)

Deprecates `dartHostTestHandler`, in preparation for removing sometime in 2026 if no significant new information comes to light.

Part of flutter/flutter#178322

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: stuartmorgan-g

packages/pigeon/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 26.1.0
+
+* Deprecates `dartHostTestHandler` and `dartTestOut`.
+  * If you have a use case where this cannot easily be replaced with a mock or
+    fake of the generated Dart API, please provide details in
+    https://github.com/flutter/flutter/issues/178322.
+
 ## 26.0.5
 
 * [kotlin] Serialize custom enums as `Long` instead of `Int` to avoid `ClassCastException` on decoding.

packages/pigeon/lib/src/generator_tools.dart

@@ -15,7 +15,7 @@ import 'generator.dart';
 /// The current version of pigeon.
 ///
 /// This must match the version in pubspec.yaml.
-const String pigeonVersion = '26.0.5';
+const String pigeonVersion = '26.1.0';
 
 /// Read all the content from [stdin] to a String.
 String readStdin() {

packages/pigeon/lib/src/pigeon_lib.dart

@@ -96,7 +96,10 @@ class ConfigurePigeon {
 /// generated host-platform interface.
 class HostApi {
   /// Parametric constructor for [HostApi].
-  const HostApi({this.dartHostTestHandler});
+  const HostApi({
+    @Deprecated('Mock/fake the generated Dart API instead.')
+    this.dartHostTestHandler,
+  });
 
   /// The name of an interface generated for tests. Implement this
   /// interface and invoke `[name of this handler].setup` to receive
@@ -111,6 +114,7 @@ class HostApi {
   /// testing.
   ///
   /// Defaults to `null` in which case no handler will be generated.
+  @Deprecated('Mock/fake the generated Dart API instead.')
   final String? dartHostTestHandler;
 }
 
@@ -238,7 +242,7 @@ class PigeonOptions {
   const PigeonOptions({
     this.input,
     this.dartOut,
-    this.dartTestOut,
+    @Deprecated('Mock/fake the generated Dart API instead.') this.dartTestOut,
     this.objcHeaderOut,
     this.objcSourceOut,
     this.objcOptions,
@@ -269,6 +273,7 @@ class PigeonOptions {
   final String? dartOut;
 
   /// Path to the Dart file that will be generated for test support classes.
+  @Deprecated('Mock/fake the generated Dart API instead.')
   final String? dartTestOut;
 
   /// Path to the ".h" Objective-C file will be generated.

packages/pigeon/pubspec.yaml

@@ -2,7 +2,7 @@ name: pigeon
 description: Code generator tool to make communication between Flutter and the host platform type-safe and easier.
 repository: https://github.com/flutter/packages/tree/main/packages/pigeon
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+pigeon%22
-version: 26.0.5 # This must match the version in lib/src/generator_tools.dart
+version: 26.1.0 # This must match the version in lib/src/generator_tools.dart
 
 environment:
   sdk: ^3.7.0