Make screen timeout configurable and validate cold startup LaunchState

Add --screen-timeout-ms CLI argument (default 1800000 = 30 min) and
ScreenTimeoutMs MSBuild property so the screen timeout can be tuned
from the .proj file without code changes.

Add LaunchState validation to AndroidHelper.measure_cold_startup():
if am start reports anything other than COLD (e.g. UNKNOWN when the
screen is off), the method now throws with a clear diagnostic message
suggesting to increase --screen-timeout-ms.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: davidnguyen-tech

eng/performance/maui_scenarios_android_innerloop.proj

@@ -33,6 +33,10 @@
 
     <RunConfigsString>$(RuntimeFlavor)_$(CodegenType)</RunConfigsString>
     <InnerLoopIterations Condition="'$(InnerLoopIterations)' == ''">10</InnerLoopIterations>
+    <!-- Screen timeout must be large enough so the display stays on for the entire scenario.
+         If the screen turns off mid-run, am start reports LaunchState: UNKNOWN and omits
+         TotalTime, which breaks cold startup measurement. -->
+    <ScreenTimeoutMs Condition="'$(ScreenTimeoutMs)' == ''">1800000</ScreenTimeoutMs>
   </PropertyGroup>
 
   <!-- Remove .NET SDK packs from the Helix correlation payload to reduce transfer size.
@@ -77,7 +81,7 @@
   <ItemGroup Condition="'$(TargetsWindows)' == 'true'">
     <HelixWorkItem Include="@(MAUIAndroidInnerLoopScenario -> 'Inner Loop Device - %(Identity)')">
       <PreCommands>$(_WindowsEnvVars);$(Python) setup_helix.py $(PERFLAB_Framework)-android &quot;$(_MSBuildArgs)&quot;</PreCommands>
-      <Command>$(Python) test.py androidinnerloop --csproj-path app/MauiAndroidInnerLoop.csproj --edit-src &quot;src/MainPage.xaml.cs;src/MainPage.xaml&quot; --edit-dest &quot;app/Pages/MainPage.xaml.cs;app/Pages/MainPage.xaml&quot; --package-name com.companyname.mauiandroidinnerloop -f $(PERFLAB_Framework)-android -c Debug --msbuild-args &quot;$(_MSBuildArgs)&quot; --scenario-name &quot;%(Identity)&quot; --inner-loop-iterations $(InnerLoopIterations) $(ScenarioArgs)</Command>
+      <Command>$(Python) test.py androidinnerloop --csproj-path app/MauiAndroidInnerLoop.csproj --edit-src &quot;src/MainPage.xaml.cs;src/MainPage.xaml&quot; --edit-dest &quot;app/Pages/MainPage.xaml.cs;app/Pages/MainPage.xaml&quot; --package-name com.companyname.mauiandroidinnerloop -f $(PERFLAB_Framework)-android -c Debug --msbuild-args &quot;$(_MSBuildArgs)&quot; --scenario-name &quot;%(Identity)&quot; --inner-loop-iterations $(InnerLoopIterations) --screen-timeout-ms $(ScreenTimeoutMs) $(ScenarioArgs)</Command>
       <PostCommands>$(Python) post.py</PostCommands>
       <DownloadFilesFromResults>output.log</DownloadFilesFromResults>
     </HelixWorkItem>
@@ -87,7 +91,7 @@
   <ItemGroup Condition="'$(TargetsWindows)' != 'true'">
     <HelixWorkItem Include="@(MAUIAndroidInnerLoopScenario -> 'Inner Loop Emulator - %(Identity)')">
       <PreCommands>$(_LinuxEnvVars);$(Python) setup_helix.py $(PERFLAB_Framework)-android &quot;$(_MSBuildArgs)&quot;</PreCommands>
-      <Command>$(Python) test.py androidinnerloop --csproj-path app/MauiAndroidInnerLoop.csproj --edit-src &quot;src/MainPage.xaml.cs;src/MainPage.xaml&quot; --edit-dest &quot;app/Pages/MainPage.xaml.cs;app/Pages/MainPage.xaml&quot; --package-name com.companyname.mauiandroidinnerloop -f $(PERFLAB_Framework)-android -c Debug --msbuild-args &quot;$(_MSBuildArgs)&quot; --scenario-name &quot;%(Identity)&quot; --inner-loop-iterations $(InnerLoopIterations) $(ScenarioArgs)</Command>
+      <Command>$(Python) test.py androidinnerloop --csproj-path app/MauiAndroidInnerLoop.csproj --edit-src &quot;src/MainPage.xaml.cs;src/MainPage.xaml&quot; --edit-dest &quot;app/Pages/MainPage.xaml.cs;app/Pages/MainPage.xaml&quot; --package-name com.companyname.mauiandroidinnerloop -f $(PERFLAB_Framework)-android -c Debug --msbuild-args &quot;$(_MSBuildArgs)&quot; --scenario-name &quot;%(Identity)&quot; --inner-loop-iterations $(InnerLoopIterations) --screen-timeout-ms $(ScreenTimeoutMs) $(ScenarioArgs)</Command>
       <PostCommands>$(Python) post.py</PostCommands>
       <DownloadFilesFromResults>output.log</DownloadFilesFromResults>
     </HelixWorkItem>

src/scenarios/shared/androidhelper.py

@@ -301,6 +301,16 @@ def measure_cold_startup(self, packagename: str, activityname: str) -> int:
         # Primary: parse TotalTime or WaitTime from am start -W output
         total_match = re.search(r"TotalTime:\s*(\d+)", start_result.stdout)
         wait_match = re.search(r"WaitTime:\s*(\d+)", start_result.stdout)
+        launch_state_match = re.search(r"LaunchState:\s*(\w+)", start_result.stdout)
+        if launch_state_match:
+            launch_state = launch_state_match.group(1)
+            getLogger().info("LaunchState: %s" % launch_state)
+            if launch_state != "COLD":
+                raise Exception(
+                    "Expected LaunchState: COLD but got LaunchState: %s. "
+                    "If UNKNOWN, the device screen may have turned off mid-run — "
+                    "increase --screen-timeout-ms." % launch_state
+                )
         if total_match:
             startup_ms = int(total_match.group(1))
             getLogger().info("Startup time (TotalTime): %d ms" % startup_ms)

src/scenarios/shared/runner.py

@@ -184,6 +184,7 @@ def parseargs(self):
         androidinnerloopparser.add_argument('--msbuild-args', help='Additional MSBuild arguments', dest='msbuildargs', default='')
         androidinnerloopparser.add_argument('--package-name', help='Android package name for startup measurement (e.g. com.companyname.mauiandroidinnerloop)', dest='packagename')
         androidinnerloopparser.add_argument('--inner-loop-iterations', help='Number of incremental build+deploy+startup iterations (1+)', type=int, default=10, dest='innerloopiterations')
+        androidinnerloopparser.add_argument('--screen-timeout-ms', help='Screen timeout in milliseconds. Must be large enough so the display stays on for the entire scenario; a screen-off mid-run breaks cold startup measurement (am start reports LaunchState: UNKNOWN).', type=int, default=30 * 60 * 1000, dest='screentimeoutms')
         self.add_common_arguments(androidinnerloopparser)
 
         args = parser.parse_args()
@@ -218,6 +219,7 @@ def parseargs(self):
             self.msbuildargs = args.msbuildargs or os.environ.get('PERFLAB_MSBUILD_ARGS', '')
             self.packagename = args.packagename
             self.innerloopiterations = args.innerloopiterations
+            self.screentimeoutms = args.screentimeoutms
 
         if self.testtype == const.DEVICESTARTUP:
             self.packagepath = args.packagepath
@@ -1120,7 +1122,7 @@ def run_incremental_iteration(iteration, num_iterations, base_cmd, edit_pairs,
             # measurement impossible.
             androidHelper = AndroidHelper()
             try:
-                androidHelper.setup_device(self.packagename, packagepath=None, animationsdisabled=True, skip_install=True, skip_xharness_warmup=True, skip_package_verifier=True, skip_test_launch=True, screen_timeout_ms=30 * 60 * 1000)
+                androidHelper.setup_device(self.packagename, packagepath=None, animationsdisabled=True, skip_install=True, skip_xharness_warmup=True, skip_package_verifier=True, skip_test_launch=True, screen_timeout_ms=self.screentimeoutms)
 
                 activityname = androidHelper.activityname
                 getLogger().info("Using resolved activity: %s" % activityname)