From 952d76898cd922a6569f0797554bb412df290696 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Tue, 23 Sep 2025 21:00:20 -0700
Subject: [PATCH] analyzer_testing: Add comment about awaiting various APIs.

Change-Id: I8761223d45756ddea4ed21c59530239b8414855e
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/451122
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
---
 .../lib/analysis_rule/analysis_rule.dart       |  9 +++++++++
 .../analysis_rule/pub_package_resolution.dart  | 18 ++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/pkg/analyzer_testing/lib/analysis_rule/analysis_rule.dart b/pkg/analyzer_testing/lib/analysis_rule/analysis_rule.dart
index 0c323225da3..7791dfcf321 100644
--- a/pkg/analyzer_testing/lib/analysis_rule/analysis_rule.dart
+++ b/pkg/analyzer_testing/lib/analysis_rule/analysis_rule.dart
@@ -2,6 +2,9 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+/// @docImport 'package:analyzer/dart/analysis/results.dart';
+library;
+
 import 'dart:convert' show json;
 
 import 'package:analyzer/analysis_rule/analysis_rule.dart';
@@ -32,6 +35,9 @@ abstract class AnalysisRuleTest extends PubPackageResolutionTest {
   String get analysisRule;
 
   /// Asserts that no diagnostics are reported when resolving [content].
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertNoPubspecDiagnostics(String content) async {
     newFile(testPackagePubspecPath, content);
     var errors = await _analyzePubspecFile(content);
@@ -39,6 +45,9 @@ abstract class AnalysisRuleTest extends PubPackageResolutionTest {
   }
 
   /// Asserts that [expectedDiagnostics] are reported when resolving [content].
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertPubspecDiagnostics(
     String content,
     List<ExpectedDiagnostic> expectedDiagnostics,
diff --git a/pkg/analyzer_testing/lib/src/analysis_rule/pub_package_resolution.dart b/pkg/analyzer_testing/lib/src/analysis_rule/pub_package_resolution.dart
index 5b7019a8efa..a988a6cf0a6 100644
--- a/pkg/analyzer_testing/lib/src/analysis_rule/pub_package_resolution.dart
+++ b/pkg/analyzer_testing/lib/src/analysis_rule/pub_package_resolution.dart
@@ -195,6 +195,9 @@ class PubPackageResolutionTest with MockPackagesMixin, ResourceProviderMixin {
   /// descriptions and locations.
   ///
   /// The order in which the diagnostics were gathered is ignored.
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertDiagnostics(
     String content,
     List<ExpectedDiagnostic> expectedDiagnostics,
@@ -205,6 +208,9 @@ class PubPackageResolutionTest with MockPackagesMixin, ResourceProviderMixin {
   }
 
   /// Asserts that the diagnostics in [diagnostics] match [expectedDiagnostics].
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   void assertDiagnosticsIn(
     List<Diagnostic> diagnostics,
     List<ExpectedDiagnostic> expectedDiagnostics,
@@ -269,6 +275,9 @@ class PubPackageResolutionTest with MockPackagesMixin, ResourceProviderMixin {
   /// expected error descriptions and locations.
   ///
   /// The order in which the diagnostics were gathered is ignored.
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertDiagnosticsInFile(
     String path,
     List<ExpectedDiagnostic> expectedDiagnostics,
@@ -282,6 +291,9 @@ class PubPackageResolutionTest with MockPackagesMixin, ResourceProviderMixin {
   ///
   /// The unit at each path needs to have already been written to the file
   /// system before calling this method.
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertDiagnosticsInUnits(
     List<(String path, List<ExpectedDiagnostic> expectedDiagnostics)>
     unitsAndDiagnostics,
@@ -293,10 +305,16 @@ class PubPackageResolutionTest with MockPackagesMixin, ResourceProviderMixin {
   }
 
   /// Asserts that there are no diagnostics in the given [content].
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertNoDiagnostics(String content) async =>
       assertDiagnostics(content, const []);
 
   /// Asserts that there are no diagnostics in the file at the given [path].
+  ///
+  /// Note: Be sure to `await` any use of this API, to avoid stale analysis
+  /// results (See [DisposedAnalysisContextResult]).
   Future<void> assertNoDiagnosticsInFile(String path) async =>
       assertDiagnosticsInFile(path, const []);