Remove AGP-internal imports from VersionFetcher and migrate compileSdk/ndk reads to the public DSL - #2

…on documentation (flutter#190842)

There are 2 files in this pr. One is a document the ai used to keep
track of work. More importantly it acts kind of like issues so it
references the items in future prs. The second is user facing website
documentation. I do not know if we will use it verbatim but for the set
of prs lets treat that md doc as human understandable documentation that
we must understand before landing the next pr.

Reviewers: When the pr is out of draft and your comments are fully
addressed please prioritize this pr over other work. The review bar is
higher, the number of reviews has more people and the work for the next
pr is already done.
 - @reidbaker 
---
Standard review context for this pr stack

This is PR is part of an 11 pr stack to migrate the "newdsl"
`gradle-api` specifically in agp 9.1.0.
The complete stack has pass pre submits, post submits and customer
tests.
https://flutter-dashboard.appspot.com/#/build?repo=flutter&branch=experimental/agp-gradle-api

All of the code was LLM authored. A mix of manual prompting, automatic
prompting, several models and adversarial review. The combined sessions
are enough that I cannot include relevant prompts like I have been doing
on other prs.

If you want to review the pr stack you can find it here. These prs will
be abandoned/closed as prs land into flutter/flutter.
1. reidbaker-agent#1 (branch:
agp-api-doc)
2. reidbaker-agent#2 (branch:
agp-internal-utils)
3. reidbaker-agent#3 (branch:
agp-buildmode-deps)
4. reidbaker-agent#4 (branch:
agp-plugin-buildtypes)
5. reidbaker-agent#5 (branch:
agp-ndk-fallback)
6. reidbaker-agent#6 (branch:
agp-assets-onvariants)
7. reidbaker-agent#7 (branch:
agp-apk-copy-versioncode)
8. reidbaker-agent#8 (branch:
agp-add-to-app)
9. reidbaker-agent#9 (branch:
agp-aar-script)
10. reidbaker-agent#10 (branch:
agp-newdsl-flip)
11. reidbaker-agent#11 (branch:
agp-gradle-api)

Follow up work is tracked in
flutter#190964

This work is urgent in the sense that we are worried that android will
publish agp 10 with no opt out but not so urgent that we are willing to
break flutter users because we didn't review or understand the code
because we were in a rush.

Breaking changes are expected as part of this work. There are patterns
the android team explicitly does not want apps to use and apis that have
no equivalent.

As part of the effort to ensure this work does not slip into ai slop,
prs from this stack will be reviewed by me (@reidbaker) before asking
for review. Then we will have 2 android expert reviewers also review the
every pr.

---
Agent authored pr description
This is PR 1 of 11 in the AGP 9.1.0 / public `gradle-api` migration
stack.

It adds the contributor-facing and website draft documentation for the
Flutter Gradle Plugin's migration to the Android Gradle Plugin public
Variant API, which unblocks building Flutter Android apps with AGP's
`newDsl=true` enabled.

Part of flutter#180137 and flutter#166550.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

---------

Co-authored-by: reidbaker-agent <[email protected]>

…90957)

This is PR 2 of 11 in the AGP 9.1.0 / public `gradle-api`/ newdls
migration stack.

This PR extracts some common utilities used in the Flutter Gradle Plugin
to internal functions, to be used in upcoming PRs in this stack. It also
introduces a typesafe CompileSdkVersion that handles comparisons between
api versions and preview versions which are strings.

First attempt was here flutter#190949
this pr includes my feedback from that first review. The first attempt
did not follow the pattern of having the agent account open the pr
because of rebase shenanigans that ended up touching freeze.yml.

---
Standard review context for this pr stack

This is PR is part of an 11 pr stack to migrate the "newdsl"
`gradle-api` specifically in agp 9.1.0.
The complete stack has pass pre submits, post submits and customer
tests.
https://flutter-dashboard.appspot.com/#/build?repo=flutter&branch=experimental/agp-gradle-api

All of the code was LLM authored. A mix of manual prompting, automatic
prompting, several models and adversarial review. The combined sessions
are enough that I cannot include relevant prompts like I have been doing
on other prs.

If you want to review the pr stack you can find it here. These prs will
be abandoned/closed as prs land into flutter/flutter.
1. reidbaker-agent#1 (branch:
agp-api-doc)
2. reidbaker-agent#2 (branch:
agp-internal-utils)
3. reidbaker-agent#3 (branch:
agp-buildmode-deps)
4. reidbaker-agent#4 (branch:
agp-plugin-buildtypes)
5. reidbaker-agent#5 (branch:
agp-ndk-fallback)
6. reidbaker-agent#6 (branch:
agp-assets-onvariants)
7. reidbaker-agent#7 (branch:
agp-apk-copy-versioncode)
8. reidbaker-agent#8 (branch:
agp-add-to-app)
9. reidbaker-agent#9 (branch:
agp-aar-script)
10. reidbaker-agent#10 (branch:
agp-newdsl-flip)
11. reidbaker-agent#11 (branch:
agp-gradle-api)

This work is urgent in the sense that we are worried that android will
publish agp 10 with no opt out but not so urgent that we are willing to
break flutter users because we didn't review or understand the code
because we were in a rush.

Breaking changes are expected as part of this work. There are patterns
the android team explicitly does not want apps to use and apis that have
no equivalent.

As part of the effort to ensure this work does not slip into ai slop,
prs from this stack will be reviewed by me (@reidbaker) before asking
for review. Then we will have 2 android expert reviewers also review the
every pr.

--- 
Agent authored description. 
This is PR 2 of 11 in the AGP 9.1.0 / public `gradle-api` migration
stack.

This PR extracts some common utilities used in the Flutter Gradle Plugin
to internal functions, to be used in upcoming PRs in this stack.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

---------

Co-authored-by: reidbaker-agent <[email protected]>
Co-authored-by: Reid Baker <[email protected]>

…dependencies through the new DSL (flutter#191218)

This is PR 3 of 11 in the AGP 9.1.0 / public `gradle-api`/ newdsl
migration stack.

* It migrates many (but not all) usages of getLegacyAndroidExtension. 
* Introduces consistency in renaming of imports. 
* Adds a test to ensure we are not adding internal apis (thanks
@mboetger from pr1)
* builds the ability to run our gradle tests with multiple AGP versions
(see packages/flutter_tools/gradle/build.gradle.kts)

Between PR 3 and PR 8, an Add-to-app host app embedding a Flutter module
with a custom build type (for example "staging") gets release engine
artifacts. That means hot reload, debugger attach, and DevTools do not
operate in that build.
We can't move the work in PR 8 up but I would not want to cut a release
between this pr and 8 landing. If we keep reviewing one pr a day then
that is not a risk.

Apps impacted by this change can use matchingFallbacks to avoid this
problem (see code below).

In pr 8 we change when we look for "isDebuggable" to much later in the
gradle lifeycle when all the variants have been created which then lets
us use a new api to understand if the variant is intended to be
debuggable.

Kotlin 
```kotlin
// host app build.gradle.kts
android {
    buildTypes {
        create("staging") {
            isDebuggable = true
            applicationIdSuffix = ".staging"
            matchingFallbacks += "debug" /// This line. 
        }
    }
}
```
Groovy 
```groovy
// host app build.gradle
android {
    buildTypes {
        staging {
            debuggable true
            applicationIdSuffix ".staging"
            matchingFallbacks = ['debug'] /// This line. 
        }
    }
}
```

Depends on flutter#190957 (PR 2).
- @reidbaker 


---
Standard review context for this pr stack

This is PR is part of an 11 pr stack to migrate the "newdsl"
`gradle-api` specifically in agp 9.1.0.
The complete stack has passed presubmits, postsubmits, and customer
tests:
https://flutter-dashboard.appspot.com/#/build?repo=flutter&branch=experimental/agp-gradle-api

All of the code was LLM authored. A mix of manual prompting, automatic
prompting, several models and adversarial review. The combined sessions
are enough that I cannot include relevant prompts like I have been doing
on other prs.

If you want to review the pr stack you can find it here. These prs will
be abandoned/closed as prs land into flutter/flutter.
1. reidbaker-agent#1 (branch:
agp-api-doc)
2. reidbaker-agent#2 (branch:
agp-internal-utils)
3. reidbaker-agent#3 (branch:
agp-buildmode-deps)
4. reidbaker-agent#4 (branch:
agp-plugin-buildtypes)
5. reidbaker-agent#5 (branch:
agp-ndk-fallback)
6. reidbaker-agent#6 (branch:
agp-assets-onvariants)
7. reidbaker-agent#7 (branch:
agp-apk-copy-versioncode)
8. reidbaker-agent#8 (branch:
agp-add-to-app)
9. reidbaker-agent#9 (branch:
agp-aar-script)
10. reidbaker-agent#10 (branch:
agp-newdsl-flip)
11. reidbaker-agent#11 (branch:
agp-gradle-api)

This work is urgent in the sense that we are worried that android will
publish agp 10 with no opt out but not so urgent that we are willing to
break flutter users because we didn't review or understand the code
because we were in a rush.

Breaking changes are expected as part of this work. There are patterns
the android team explicitly does not want apps to use and apis that have
no equivalent.

As part of the effort to ensure this work does not slip into ai slop,
prs from this stack will be reviewed by me (@reidbaker) before asking
for review. Then we will have 2 android expert reviewers also review
every pr.

--- 
Agent authored description. 
This is PR 3 of 11 in the AGP 9.1.0 / public `gradle-api` migration
stack (flutter#180137, flutter#166550).

### Key Changes
- **DSL Build Mode Overloads**: Adds `buildModeFor` overloads accepting
`ApplicationBuildType`, `DynamicFeatureBuildType`, and
`LibraryBuildType` DSL types alongside the `(buildTypeName,
isDebuggable)` core overload.
- **Robust CompileSdkVersion Domain Model**: Extracts
`CompileSdkVersion` with constructor invariant validation (`init {
require(...) }`) enforcing mutual exclusivity between `apiLevel` and
`previewCodename`.
- **Namespaced Multi-AGP Build Property**: Namespaces the AGP version
property in `packages/flutter_tools/gradle/build.gradle.kts` as
`flutter.internal.agpVersion` (defaulting to `8.11.1`) to prevent user
app properties from leaking into the included build during app
compilation.
- **Standardized Type Aliasing**: Applies non-temporal type aliasing
(`import com.android.build.api.dsl.BuildType as DslBuildType`) across
`FlutterPlugin.kt` and `PluginHandler.kt`.
- **Public DSL Extension Access**: Updates `addFlutterDependencies` and
`PluginHandler` to iterate `AgpCommonExtensionWrapper.buildTypes`.
- **Build & Bytecode Validation**: Adds the
`:validateNoCommonExtensionInBytecode` task in `build.gradle.kts` to
prevent compiled main classes from referencing binary-incompatible
`CommonExtension`, and adds `BytecodeValidatorTest.kt` verifying the
binary pattern-matching and class scanning logic.
- **Comprehensive Unit Tests**: Adds full 4-way dispatch test coverage
in `AgpCommonExtensionWrapperTest`, dependency wiring tests in
`FlutterPluginTest`, and decomposes `PluginHandlerTest` mock fixtures
into focused helpers with positive assertions.

### Add-to-App & DSL Scope Context
`LibraryBuildType` does not expose `isDebuggable` at DSL scope. In PR 3,
custom build types on library projects (e.g. host app 'staging') fall
back to `"release"` at DSL scope. In PR 8 ("Unify add-to-app module
wiring on the variant API"), module wiring will be unified on
`Component.debuggable` at variant scope.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

---------

Co-authored-by: reidbaker-agent <[email protected]>
Co-authored-by: Reid Baker <[email protected]>

…nitWith on public DSL (flutter#191606)

This is PR 4 of 11 in the AGP 9.1.0 / public `gradle-api` / newdsl
migration stack.

There are no breaking changes expected in this pr. Only internal logic
is impacted.

I will be honest I also found the tests hard to review. I had the agent
pull out shared mocking logic but I am not sure that actually made
review easier.

Depends on flutter#191218 (PR 3).
- @reidbaker

---
Standard review context for this pr stack

This is PR is part of an 11 pr stack to migrate the "newdsl"
`gradle-api` specifically in agp 9.1.0.

All of the code was LLM authored. A mix of manual prompting, automatic
prompting, several models and adversarial review. The combined sessions
are enough that I cannot include relevant prompts like I have been doing
on other prs.

If you want to review the pr stack you can find it here. These prs will
be abandoned/closed as prs land into flutter/flutter.
1. reidbaker-agent#1 (branch:
agp-api-doc)
2. reidbaker-agent#2 (branch:
agp-internal-utils)
3. reidbaker-agent#3 (branch:
agp-buildmode-deps)
4. reidbaker-agent#4 (branch:
agp-plugin-buildtypes)
5. reidbaker-agent#5 (branch:
agp-ndk-fallback)
6. reidbaker-agent#6 (branch:
agp-assets-onvariants)
7. reidbaker-agent#7 (branch:
agp-apk-copy-versioncode)
8. reidbaker-agent#8 (branch:
agp-add-to-app)
9. reidbaker-agent#9 (branch:
agp-aar-script)
10. reidbaker-agent#10 (branch:
agp-newdsl-flip)
11. reidbaker-agent#11 (branch:
agp-gradle-api)

This work is urgent in the sense that we are worried that android will
publish agp 10 with no opt out but not so urgent that we are willing to
break flutter users because we didn't review or understand the code
because we were in a rush.

Breaking changes are expected as part of this work. There are patterns
the android team explicitly does not want apps to use and apis that have
no equivalent.

As part of the effort to ensure this work does not slip into ai slop,
prs from this stack will be reviewed by me (@reidbaker) before asking
for review. Then we will have 2 android expert reviewers also review
every pr.

---
Agent authored description.
This is PR 4 of 11 in the AGP 9.1.0 / public `gradle-api` migration
stack (flutter#180137, flutter#166550).

### Key Changes
- **Public DSL `initWith` Copy**: Replaces the legacy
`getLegacyAndroidExtension` build-type copy in `PluginHandler` with
`initWith` on the public DSL (`AgpCommonExtensionWrapper.buildTypes`).
Missing build types on the plugin project are created with
`initWith(appBuildType)`, and `isDebuggable` is copied when both sides
are `ApplicationBuildType`.
- **Zero AGP Internals in Production Sources**: Removes the last
remaining `com.android.build.gradle.internal` imports from production
code (`src/main`).
- **Internal AGP Import Guard**: Adds `InternalAgpApiImportTest` to
continuously enforce that production sources do not introduce
`com.android.build.gradle.internal.*` imports.
- **Decomposed & Robust Unit Tests**: Replaces legacy mock-only tests in
`PluginHandlerTest` with tests that execute `configurePlugins` and
verify `initWith` copying for both library and application plugin
projects, mapping custom debuggable build types to debug engine
artifacts, and verifying that pre-existing plugin build types are
skipped.
- **Migration Documentation Update**: Adds details for the P3 pre-spike
and `finalizeDsl` fallback in
`Migrating-Flutter-Gradle-Plugin-to-AGP-public-API.md`.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

… NDK fallback to public DSL (flutter#192116)

This is PR 5 of 11 in the AGP 9.1.0 / public `gradle-api` / newdsl
migration stack.

Add externalNativeBuild to the shared type. Extracted some shared
mocking logic to a utility.
No external visible changes expected. 
Also improved the README.md so that the test file for multiple agp
versions was a markdown link.

- @reidbaker

---
Standard review context for this pr stack

This is PR is part of an 11 pr stack to migrate the "newdsl"
`gradle-api` specifically in agp 9.1.0.

All of the code was LLM authored. A mix of manual prompting, automatic
prompting, several models and adversarial review. The combined sessions
are enough that I cannot include relevant prompts like I have been doing
on other prs.

If you want to review the pr stack you can find it here. These prs will
be abandoned/closed as prs land into flutter/flutter.
1. reidbaker-agent#1 (branch:
agp-api-doc)
2. reidbaker-agent#2 (branch:
agp-internal-utils)
3. reidbaker-agent#3 (branch:
agp-buildmode-deps)
4. reidbaker-agent#4 (branch:
agp-plugin-buildtypes)
5. reidbaker-agent#5 (branch:
agp-ndk-fallback)
6. reidbaker-agent#6 (branch:
agp-assets-onvariants)
7. reidbaker-agent#7 (branch:
agp-apk-copy-versioncode)
8. reidbaker-agent#8 (branch:
agp-add-to-app)
9. reidbaker-agent#9 (branch:
agp-aar-script)
10. reidbaker-agent#10 (branch:
agp-newdsl-flip)
11. reidbaker-agent#11 (branch:
agp-gradle-api)

This work is urgent in the sense that we are worried that android will
publish agp 10 with no opt out but not so urgent that we are willing to
break flutter users because we didn't review or understand the code
because we were in a rush.

Breaking changes are expected as part of this work. There are patterns
the android team explicitly does not want apps to use and apis that have
no equivalent.

As part of the effort to ensure this work does not slip into ai slop,
prs from this stack will be reviewed by me (@reidbaker) before asking
for review. Then we will have 2 android expert reviewers also review
every pr.

---
Agent authored description.
This is PR 5 of 11 in the AGP 9.1.0 / public `gradle-api` migration
stack (flutter#180137, flutter#166550).

### Key Changes
- **Public DSL Wrapper `externalNativeBuild`**: Exposes `val
externalNativeBuild: ExternalNativeBuild` in
`AgpCommonExtensionWrapper.kt` dispatching across
`ApplicationExtension`, `LibraryExtension`, `DynamicFeatureExtension`,
and `TestExtension` without referencing `CommonExtension` (bypassing AGP
binary incompatibility).
- **Zero Legacy `BaseExtension` in Production Sources**: Deletes
`getLegacyAndroidExtension(project: Project): BaseExtension` and removes
the `com.android.build.gradle.BaseExtension` import from
`FlutterPluginUtils.kt`.
- **Public DSL NDK Fallback Configuration**: Migrates `forceNdkDownload`
and `configureSyntheticExternalNativeBuildFallback` in
`FlutterPluginUtils.kt` to `getAndroidExtension(gradleProject)` using
`externalNativeBuild.cmake` / `externalNativeBuild.ndkBuild`. Sets
`cmake.path = File(...)`, `cmake.buildStagingDirectory = ...`, and
`buildType.externalNativeBuild.cmake.arguments += ...` through the
public DSL while preserving the upstream PR flutter#187201 `ndkBuild.path`
check.
- **Unit Test Public DSL Mocking & Cleanup**: Migrates unit tests in
`FlutterPluginUtilsTest.kt` to mock public DSL types
(`ApplicationExtension`, `Cmake`, `NdkBuild`), asserts CMake arguments
by list content, deletes obsolete tests asserting
`ApplicationExtension`-vs-`BaseExtension` `ndkVersion` preference, and
removes unused `import io.mockk.called` as well as all legacy
`com.android.build.gradle.internal.*` imports.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

…#192650)

Fixes flutter#192227

**Problem**

`AppDomain.launch` sends the `app.start` event, which carries the app
ID, before `ResidentRunner.run()` has compiled and called
`generator.accept()`. A client that acts on that ID immediately can land
an `app.restart` in the gap, producing a `recompile` against a compiler
with no accepted baseline. `frontend_server` then crashes on
`lastKnownGoodResult!`, and the app fails to start.

**Fix**

`AppDomain.restart` now waits on a new `AppInstance.started` before
entering the debounce queue, so the compiler is never asked to recompile
before it has a baseline.

**Demo**

No URLs: the bug is in the `flutter run --machine` daemon protocol, not
in rendered output, so a deployed build has no daemon to race.

Verified locally with a harness that sends `app.restart` during the
initial compile, which is the window this closes. Before, it reproduces
the exact trace from the issue and the app
dies:

    Null check operator used on a null value
#0 FrontendCompiler.writeJavaScriptBundle (frontend_server.dart:1100)
#1 FrontendCompiler.recompileDelta (frontend_server.dart:1312)
#2 listenAndCompile.<anonymous closure> (frontend_server.dart:1806)
    App failed to start

After, the restart is held until `app.started` and returns `code: 0`.

Fixes flutter#110488.

### Background: The `testWidgets` Lifecycle
Understanding this change requires distinguishing between two layers of
`Future`s and two distinct verification steps in `testWidgets`:

#### 1. Two Layers of `Future`s
* **`testBody()` Future**: The closure containing the user's test logic.
* **`runTest()` Future**: The overall async harness returned by
`binding.runTest()`. It manages the test zone, unmounts the widget tree,
and resolves only after `testBody()` and test-specific verifications
finish.

#### 2. Two Distinct Verification Phases
* **Test-specific verifications (`invariantTester`)**: Passed as a
callback to `runTest` and executed synchronously inside `_runTestBody`
immediately after the `testBody()` Future completes and the widget tree
is unmounted. In `testWidgets`, this runs
`tester._endOfTestVerifications` to verify that tickers and semantics
handles were disposed.
* **Framework-level invariant checks**: Verifies global framework state,
including ensuring foundation/rendering/widgets debug flags were reset
and no non-periodic timers or animations remain.

#### 3. The Teardown Lifecycle & Root Cause of flutter#110488
When `testWidgets` runs:
1. `testWidgets` registers `test_package.addTearDown(binding.postTest)`
with `package:test`.
2. `testWidgets` calls and returns `binding.runTest(...)`.
3. Inside `testBody()`, users may register cleanups using `addTearDown`
(for example, `addTearDown(() => debugDefaultTargetPlatformOverride =
null)`).
4. `package:test` executes teardowns in **LIFO (reverse registration)
order** only *after* the Future returned by `runTest` completes.

Previously, framework-level invariant checks ran at the end of
`_runTestBody` *before* the `runTest` Future completed. As a result,
they ran before `package:test` executed any user-registered
`addTearDown` callbacks, causing tests that clean up debug flags via
`addTearDown` to fail invariant verification (flutter#110488).

The following diagram shows the code flow after this PR:
```
testWidgets(description, (tester) async { ... })
 │
 ├── 1. Registration Phase
 │    └── test_package.addTearDown(binding.postTest)     [Teardown Stack: #1]
 │
 ├── 2. Test Execution Phase: binding.runTest(...)
 │    │
 │    │   [ Future 1: testBody() ]
 │    ├──► Run testBody(tester)
 │    │     └── User calls addTearDown(...)              [Teardown Stack: #2]
 │    │
 │    │   [ Post-testBody cleanup (inside runTest) ]
 │    ├──► Unmount widget tree (runApp)
 │    ├──► Verification 1: invariantTester()             (tickers, semantics)
 │    └──► Set _shouldVerifyInvariants = true
 │
 │    [ Future 2: runTest() completes ]
 │
 └── 3. Teardown Phase: package:test executes in LIFO order
      │
      ├──► [Step 1] User Teardowns (Stack #2)
      │     └── e.g., debugDefaultTargetPlatformOverride = null
      │
      └──► [Step 2] binding.postTest() (Stack #1)
            ├── Verification 2: Framework Invariants     (debug vars, timers)
            ├── Reset Binding State                      (_currentFakeAsync, etc.)
            └── reportTestException(...)                 (if Verification 2 failed)
```
### Changes & Design Rationale
#### 1. Defer Framework Invariant Checks to `postTest`

Framework invariant checks (`_verifyInvariants()`,
`_verifyAutoUpdateGoldensUnset`, etc.) are moved from `_runTestBody`
into `TestWidgetsFlutterBinding.postTest`.
Because `testWidgets` registers `binding.postTest` before running the
test body, `package:test`'s LIFO teardown ordering guarantees that all
user-registered `addTearDown` callbacks execute before
`binding.postTest`.

#### 2. Clarifying the `postTest` Error Contract

Previously, `postTest` only performed state cleanup and did not check
invariants. Moving invariant checks into `postTest` introduced the
question of how invariant failures should be propagated: allowing
`postTest` to throw, or absorbing errors and reporting them via
`reportTestException`.

We explicitly define the contract of `postTest` to **not throw
exceptions**, reporting any invariant failures via
`reportTestException`:

* **Rationale & Trade-offs**:
* *Alternative considered (throwing)*: If `super.postTest()` threw on an
invariant failure, `package:test` would still capture the failure.
However, subclasses (`AutomatedTestWidgetsFlutterBinding`,
`LiveTestWidgetsFlutterBinding`, or custom bindings) override `postTest`
to reset their own state (e.g. nulling `_currentFakeAsync` / `_clock`,
or setting `_inTest = false`). Allowing `super.postTest()` to throw
would require every subclass to defensively wrap `super.postTest()` in
`try ... finally`. If any subclass omitted this, an invariant failure
would leave the binding in a dirty state and trigger cascading `!inTest`
failures in subsequent tests.
* *Chosen approach (non-throwing)*: Absorbing errors in `postTest` and
forwarding them to `reportTestException` guarantees that all cleanup in
base and subclass implementations executes sequentially without
defensive `try ... finally` boilerplate, while still cleanly failing the
test.

**Why this does not break existing behavior:**
In the previous implementation, when invariant assertions failed inside
`_runTestBody`, they were caught by `_testZone.handleUncaughtError` and
forwarded to `reportTestException` (which delegates to
`package:test.registerException`). They never escaped `runTest` as
unhandled thrown exceptions. Catching invariant failures in `postTest`
and routing them to `reportTestException` preserves this exact error
reporting pipeline, diagnostic output, and failure semantics without
disrupting teardown execution.

#### 3. Preserving Existing Behavior on Failed Tests
(`_shouldVerifyInvariants`)

Historically, `_runTestBody` only verified invariants if the test body
did not fail:

```dart
if (_pendingExceptionDetails == null) {
  // We only try to clean up and verify invariants if we didn't already
  // fail. If we got an exception already, then we instead leave everything
  // alone so that we don't cause more spurious errors.
  ...
  _verifyInvariants();
}
```

When invariant checks are moved to `postTest`,
`_pendingExceptionDetails` is no longer available because it has already
been reported and cleared by `testCompletionHandler` when `runTest`
completed.

To preserve this exact existing behavior across the lifecycle boundary,
`_shouldVerifyInvariants` is introduced. It is set to `true` at the end
of `_runTestBody` only when `_pendingExceptionDetails == null`. If a
test fails in its body, `_shouldVerifyInvariants` remains `false`, and
`postTest` skips invariant checks—ensuring no behavior change and
preventing spurious errors (e.g. active animations on an unmounted tree)
from masking the real failure.

#### 4. Documentation Updates
Updated the doc comments on:
* `TestWidgetsFlutterBinding.postTest`: Documents the non-throwing
contract, the `@mustCallSuper` requirement, and error reporting via
`reportTestException`.
* `TestWidgetsFlutterBinding.runTest`: Clarifies the distinction between
`invariantTester` (which runs before `runTest` completes) and framework
invariant checks (which run in `postTest` after `runTest` and user
teardowns complete).

### Tests
- Added unit tests in
`packages/flutter_test/test/bindings_invariants_test.dart` verifying
that foundation variables (`debugDefaultTargetPlatformOverride`,
`debugDoublePrecision`, `debugBrightnessOverride`),
`autoUpdateGoldenFiles`, `ErrorWidget.builder`, and
`shouldPropagateDevicePointerEvents` can all be reset using
`addTearDown`.
- Added test cases verifying invariant failures in `postTest` and
ensuring invariant checks are skipped when the test body throws.

## Pre-launch Checklist

- [ ] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [ ] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [ ] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [ ] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [ ] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [ ] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [ ] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

If this change needs to override an active code freeze, provide a
comment explaining why. The code freeze workflow can be overridden by
code reviewers. See pinned issues for any active code freezes with
guidance.

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[AI contribution guidelines]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

)

Reverts: [Allow resetting test invariants in
`addTearDown`](flutter#192082)

Initiated by: @b-luk

Reason for reverting: Breaks tree with tool_integration_tests failures.
Example:
https://ci.chromium.org/ui/p/flutter/builders/prod/Mac%20tool_integration_tests_2/1329/overview

Original PR Author: @dkwingsmt

Reviewed By: @justinmc

The original PR description is provided below:

Fixes flutter#110488.

### Background: The `testWidgets` Lifecycle
Understanding this change requires distinguishing between two layers of
`Future`s and two distinct verification steps in `testWidgets`:

#### 1. Two Layers of `Future`s
* **`testBody()` Future**: The closure containing the user's test logic.
* **`runTest()` Future**: The overall async harness returned by
`binding.runTest()`. It manages the test zone, unmounts the widget tree,
and resolves only after `testBody()` and test-specific verifications
finish.

#### 2. Two Distinct Verification Phases
* **Test-specific verifications (`invariantTester`)**: Passed as a
callback to `runTest` and executed synchronously inside `_runTestBody`
immediately after the `testBody()` Future completes and the widget tree
is unmounted. In `testWidgets`, this runs
`tester._endOfTestVerifications` to verify that tickers and semantics
handles were disposed.
* **Framework-level invariant checks**: Verifies global framework state,
including ensuring foundation/rendering/widgets debug flags were reset
and no non-periodic timers or animations remain.

#### 3. The Teardown Lifecycle & Root Cause of flutter#110488
When `testWidgets` runs:
1. `testWidgets` registers `test_package.addTearDown(binding.postTest)`
with `package:test`.
2. `testWidgets` calls and returns `binding.runTest(...)`.
3. Inside `testBody()`, users may register cleanups using `addTearDown`
(for example, `addTearDown(() => debugDefaultTargetPlatformOverride =
null)`).
4. `package:test` executes teardowns in **LIFO (reverse registration)
order** only *after* the Future returned by `runTest` completes.

Previously, framework-level invariant checks ran at the end of
`_runTestBody` *before* the `runTest` Future completed. As a result,
they ran before `package:test` executed any user-registered
`addTearDown` callbacks, causing tests that clean up debug flags via
`addTearDown` to fail invariant verification (flutter#110488).

The following diagram shows the code flow after this PR:
```
testWidgets(description, (tester) async { ... })
 │
 ├── 1. Registration Phase
 │    └── test_package.addTearDown(binding.postTest)     [Teardown Stack: #1]
 │
 ├── 2. Test Execution Phase: binding.runTest(...)
 │    │
 │    │   [ Future 1: testBody() ]
 │    ├──► Run testBody(tester)
 │    │     └── User calls addTearDown(...)              [Teardown Stack: #2]
 │    │
 │    │   [ Post-testBody cleanup (inside runTest) ]
 │    ├──► Unmount widget tree (runApp)
 │    ├──► Verification 1: invariantTester()             (tickers, semantics)
 │    └──► Set _shouldVerifyInvariants = true
 │
 │    [ Future 2: runTest() completes ]
 │
 └── 3. Teardown Phase: package:test executes in LIFO order
      │
      ├──► [Step 1] User Teardowns (Stack #2)
      │     └── e.g., debugDefaultTargetPlatformOverride = null
      │
      └──► [Step 2] binding.postTest() (Stack #1)
            ├── Verification 2: Framework Invariants     (debug vars, timers)
            ├── Reset Binding State                      (_currentFakeAsync, etc.)
            └── reportTestException(...)                 (if Verification 2 failed)
```
### Changes & Design Rationale
#### 1. Defer Framework Invariant Checks to `postTest`

Framework invariant checks (`_verifyInvariants()`,
`_verifyAutoUpdateGoldensUnset`, etc.) are moved from `_runTestBody`
into `TestWidgetsFlutterBinding.postTest`.
Because `testWidgets` registers `binding.postTest` before running the
test body, `package:test`'s LIFO teardown ordering guarantees that all
user-registered `addTearDown` callbacks execute before
`binding.postTest`.

#### 2. Clarifying the `postTest` Error Contract

Previously, `postTest` only performed state cleanup and did not check
invariants. Moving invariant checks into `postTest` introduced the
question of how invariant failures should be propagated: allowing
`postTest` to throw, or absorbing errors and reporting them via
`reportTestException`.

We explicitly define the contract of `postTest` to **not throw
exceptions**, reporting any invariant failures via
`reportTestException`:

* **Rationale & Trade-offs**:
* *Alternative considered (throwing)*: If `super.postTest()` threw on an
invariant failure, `package:test` would still capture the failure.
However, subclasses (`AutomatedTestWidgetsFlutterBinding`,
`LiveTestWidgetsFlutterBinding`, or custom bindings) override `postTest`
to reset their own state (e.g. nulling `_currentFakeAsync` / `_clock`,
or setting `_inTest = false`). Allowing `super.postTest()` to throw
would require every subclass to defensively wrap `super.postTest()` in
`try ... finally`. If any subclass omitted this, an invariant failure
would leave the binding in a dirty state and trigger cascading `!inTest`
failures in subsequent tests.
* *Chosen approach (non-throwing)*: Absorbing errors in `postTest` and
forwarding them to `reportTestException` guarantees that all cleanup in
base and subclass implementations executes sequentially without
defensive `try ... finally` boilerplate, while still cleanly failing the
test.

**Why this does not break existing behavior:**
In the previous implementation, when invariant assertions failed inside
`_runTestBody`, they were caught by `_testZone.handleUncaughtError` and
forwarded to `reportTestException` (which delegates to
`package:test.registerException`). They never escaped `runTest` as
unhandled thrown exceptions. Catching invariant failures in `postTest`
and routing them to `reportTestException` preserves this exact error
reporting pipeline, diagnostic output, and failure semantics without
disrupting teardown execution.

#### 3. Preserving Existing Behavior on Failed Tests
(`_shouldVerifyInvariants`)

Historically, `_runTestBody` only verified invariants if the test body
did not fail:

```dart
if (_pendingExceptionDetails == null) {
  // We only try to clean up and verify invariants if we didn't already
  // fail. If we got an exception already, then we instead leave everything
  // alone so that we don't cause more spurious errors.
  ...
  _verifyInvariants();
}
```

When invariant checks are moved to `postTest`,
`_pendingExceptionDetails` is no longer available because it has already
been reported and cleared by `testCompletionHandler` when `runTest`
completed.

To preserve this exact existing behavior across the lifecycle boundary,
`_shouldVerifyInvariants` is introduced. It is set to `true` at the end
of `_runTestBody` only when `_pendingExceptionDetails == null`. If a
test fails in its body, `_shouldVerifyInvariants` remains `false`, and
`postTest` skips invariant checks—ensuring no behavior change and
preventing spurious errors (e.g. active animations on an unmounted tree)
from masking the real failure.

#### 4. Documentation Updates
Updated the doc comments on:
* `TestWidgetsFlutterBinding.postTest`: Documents the non-throwing
contract, the `@mustCallSuper` requirement, and error reporting via
`reportTestException`.
* `TestWidgetsFlutterBinding.runTest`: Clarifies the distinction between
`invariantTester` (which runs before `runTest` completes) and framework
invariant checks (which run in `postTest` after `runTest` and user
teardowns complete).

### Tests
- Added unit tests in
`packages/flutter_test/test/bindings_invariants_test.dart` verifying
that foundation variables (`debugDefaultTargetPlatformOverride`,
`debugDoublePrecision`, `debugBrightnessOverride`),
`autoUpdateGoldenFiles`, `ErrorWidget.builder`, and
`shouldPropagateDevicePointerEvents` can all be reset using
`addTearDown`.
- Added test cases verifying invariant failures in `postTest` and
ensuring invariant checks are skipped when the test body throws.

## Pre-launch Checklist

- [ ] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [ ] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [ ] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [ ] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [ ] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [ ] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [ ] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

If this change needs to override an active code freeze, provide a
comment explaining why. The code freeze workflow can be overridden by
code reviewers. See pinned issues for any active code freezes with
guidance.

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[AI contribution guidelines]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Issue: flutter#193579.

This is a fix for the following error:
```
Processing /Volumes/Work/s/w/ir/x/w/flutter/bin/cache/pkg/tests/registry/flutter_cocoon.test...
Unhandled exception:
ProcessException: No such file or directory
  Command: ./test_utilities/bin/flutter_test_runner.sh dashboard
#0      _ProcessImpl._start (dart:io-patch/process_patch.dart:411:33)
#1      Process.start (dart:io-patch/process_patch.dart:42:20)
#2      shell (file:///Volumes/Work/s/w/ir/x/w/flutter/dev/customer_testing/lib/runner.dart:236:29)
#3      runTests (file:///Volumes/Work/s/w/ir/x/w/flutter/dev/customer_testing/lib/runner.dart:172:31)
<asynchronous suspension>
#4      main (file:///Volumes/Work/s/w/ir/x/w/flutter/dev/customer_testing/run_tests.dart:15:8)
<asynchronous suspension>
```

…rror 206) (flutter#194867)

When a Flutter project, SDK, or subprocess command path on Windows
exceeds `MAX_PATH` (260 characters), Win32 process and file operations
fail with OS error code `206` (`ERROR_FILENAME_EXCED_RANGE`: `The
filename or extension is too long`). Previously,
`_handleWindowsException` in `error_handling_io.dart` did not recognize
error code `206`, causing `ErrorHandlingProcessManager` and
`ErrorHandlingFileSystem` to rethrow an unhandled
`ProcessPackageException` or `FileSystemException` and trigger a crash
report.

Add `kFilenameExcedRange = 206` to `_handleWindowsException` so
operations failing with error code `206` exit cleanly with a `ToolExit`
instructing the user to move the Flutter SDK and/or project to a shorter
path or enable long paths on Windows.

### Previous output
```text
Unhandled exception:
ProcessPackageException: ProcessException: The filename or extension is too long
  Command: C:\Users\User\AppData\Local\Temp\...
#0      LocalProcessManager.runSync (package:process/src/interface/local_process_manager.dart:118)
#1      ErrorHandlingProcessManager.runSync.<anonymous closure> (package:flutter_tools/src/base/error_handling_io.dart:1310)
#2      _runSync (package:flutter_tools/src/base/error_handling_io.dart:1118)
#3      ErrorHandlingProcessManager.runSync (package:flutter_tools/src/base/error_handling_io.dart:1308)
#4      _DefaultPub._preloadPubCache (package:flutter_tools/src/dart/pub.dart:645)
```

### Current output
```text
Flutter failed to run "C:\Users\User\AppData\Local\Temp\...". The filename or extension is too long.
ProcessException: The filename or extension is too long
  Command: C:\Users\User\AppData\Local\Temp\...
Please consider moving the Flutter SDK and/or project to a shorter path, or enabling long paths on Windows.
```

Fixes flutter#194570