[pipeline] feat: Implement flexible UI test pipeline with configurable build and execution modes (#40490)

<!-- Enter a brief description/summary of your PR here. What does it
fix/what does it change/how was it tested (even manually, if necessary)?
-->
## Summary of the Pull Request
**Root Cause:**
The current pipeline builds the entire solution and runs all UI tests
every time, which takes more than 2 hours to complete.

**Fix**
Make the PowerToys UI test pipeline provides flexible options for
building and testing:

### Pipeline Options

- **useLatestOfficialBuild**: When checked, downloads the latest
official PowerToys build and installs it for testing. This skips the
full solution build and only builds UI test projects.

- **useCurrentBranchBuild**: When checked along with
`useLatestOfficialBuild`, downloads the official build from the current
branch instead of main.

- **uiTestModules**: Specify which UI test modules to build and run.
Examples:
  - `UITests-FancyZones` - Only FancyZones UI tests
  - `MouseUtils.UITests` - Only MouseUtils UI tests
- `['UITests-FancyZones', 'MouseUtils.UITests']` - Multiple specific
modules
  - Leave empty to build and run all UI test modules

### Build Modes

1. **Official Build + Selective Testing** (`useLatestOfficialBuild =
true`)
   - Downloads and installs official PowerToys build
   - Builds only specified UI test projects
   - Runs specified UI tests against installed PowerToys
   - Controlled by `uiTestModules` parameter

2. **Full Build + Testing** (`useLatestOfficialBuild = false`)
   - Builds entire PowerToys solution
   - Builds UI test projects (all or specific based on `uiTestModules`)
   - Runs UI tests (all or specific based on `uiTestModules`)
   - Uses freshly built PowerToys for testing
  
<!-- Please review the items on the PR checklist before submitting-->
## PR Checklist

- [ ] **Closes:** #xxx
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [x] **Tests:** Added/updated and all pass
- [ ] **Localization:** All end-user-facing strings can be localized
- [x] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

<!-- Provide a more detailed description of the PR, other things fixed,
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments

<!-- Describe how you validated the behavior. Add automated tests
wherever possible, but list manual validation steps taken as well -->
## Validation Steps Performed

.pipelines/v2/templates/job-build-ui-tests.yml

@@ -0,0 +1,132 @@
+# Minimal UI Tests Build Template
+# This template only builds UI test projects and stages their test DLLs for consumption by test pipelines
+
+parameters:
+  - name: buildConfigurations
+    type: object
+    default:
+      - Release
+  - name: buildPlatforms
+    type: object
+    default:
+      - x64
+  - name: condition
+    type: string
+    default: ''
+  - name: dependsOn
+    type: object
+    default: []
+  - name: pool
+    type: object
+    default: []
+  - name: variables
+    type: object
+    default: {}
+  - name: uiTestModules
+    type: object
+    default: []
+
+jobs:
+- job: BuildUITests
+  ${{ if ne(length(parameters.pool), 0) }}:
+    pool: ${{ parameters.pool }}
+  dependsOn: ${{ parameters.dependsOn }}
+  condition: ${{ parameters.condition }}
+  strategy:
+    matrix:
+      ${{ each config in parameters.buildConfigurations }}:
+        ${{ each platform in parameters.buildPlatforms }}:
+          ${{ config }}_${{ platform }}:
+            BuildConfiguration: ${{ config }}
+            BuildPlatform: ${{ platform }}
+  variables:
+    JobOutputDirectory: $(Build.ArtifactStagingDirectory)
+    LogOutputDirectory: $(Build.ArtifactStagingDirectory)\logs
+    JobOutputArtifactName: build-$(BuildPlatform)-$(BuildConfiguration)
+    NUGET_RESTORE_MSBUILD_ARGS: /p:Platform=$(BuildPlatform)
+    ${{ insert }}: ${{ parameters.variables }}
+  displayName: Build UI Tests Only
+  timeoutInMinutes: 60
+  cancelTimeoutInMinutes: 1
+  templateContext:
+    outputs:
+    - output: pipelineArtifact
+      artifactName: $(JobOutputArtifactName)
+      targetPath: $(Build.ArtifactStagingDirectory)
+  steps:
+  - checkout: self
+    clean: true
+    submodules: true
+    persistCredentials: True
+    fetchTags: false
+    fetchDepth: 1
+
+  - template: steps-ensure-dotnet-version.yml
+    parameters:
+      sdk: true
+      version: '9.0'
+
+  - template: .\steps-restore-nuget.yml
+
+  - task: NuGetCommand@2
+    displayName: Restore solution-level NuGet packages
+    inputs:
+      command: restore
+      feedsToUse: config
+      configPath: nuget.config
+      restoreSolution: PowerToys.sln
+      restoreDirectory: '$(Build.SourcesDirectory)\packages'
+
+  # Build all UI test projects if no specific modules are specified
+  - ${{ if eq(length(parameters.uiTestModules), 0) }}:
+    - task: VSBuild@1
+      displayName: Build UI Test Projects
+      inputs:
+        solution: '**/*UITest*.csproj'
+        vsVersion: 17.0
+        msbuildArgs: >-
+          -restore
+          -graph
+          /p:RestorePackagesConfig=true
+          /p:BuildProjectReferences=true
+          /p:CIBuild=true
+          /bl:$(LogOutputDirectory)\build-all-uitests.binlog
+          $(NUGET_RESTORE_MSBUILD_ARGS)
+        platform: $(BuildPlatform)
+        configuration: $(BuildConfiguration)
+        msbuildArchitecture: x64
+        maximumCpuCount: true
+
+  # Build specific UI test modules
+  - ${{ if ne(length(parameters.uiTestModules), 0) }}:
+    - ${{ each module in parameters.uiTestModules }}:
+      - task: VSBuild@1
+        displayName: 'Build UI Test Module: ${{ module }}'
+        inputs:
+          solution: '**/*${{ module }}*.csproj'
+          vsVersion: 17.0
+          msbuildArgs: >-
+            -restore
+            -graph
+            /p:RestorePackagesConfig=true
+            /p:BuildProjectReferences=true
+            /p:CIBuild=true
+            /bl:$(LogOutputDirectory)\build-${{ module }}.binlog
+            $(NUGET_RESTORE_MSBUILD_ARGS)
+          platform: $(BuildPlatform)
+          configuration: $(BuildConfiguration)
+          msbuildArchitecture: x64
+          maximumCpuCount: true
+
+  # Stage test project outputs with directory structure
+  - task: CopyFiles@2
+    displayName: Stage UI Test Build Outputs
+    inputs:
+      sourceFolder: '$(Build.SourcesDirectory)'
+      contents: '$(BuildPlatform)/$(BuildConfiguration)/**/*'
+      targetFolder: '$(JobOutputDirectory)\$(BuildPlatform)\$(BuildConfiguration)'
+
+  - publish: $(JobOutputDirectory)
+    artifact: $(JobOutputArtifactName)
+    displayName: Publish UI Test artifacts
+    condition: always()

.pipelines/v2/templates/job-test-project.yml

@@ -11,10 +11,28 @@ parameters:
   - name: useLatestWebView2
     type: boolean
     default: false
+  - name: useLatestOfficialBuild
+    type: boolean
+    default: true
+  - name: useCurrentBranchBuild
+    type: boolean
+    default: false
+  - name: uiTestModules
+    type: object
+    default: []
+  - name: installMode
+    type: string
+    default: 'machine'
+    values:
+      - 'machine'
+      - 'peruser'
+  - name: jobSuffix
+    type: string
+    default: ''
 
 jobs:
-- job: Test${{ parameters.platform }}${{ parameters.configuration }}
-  displayName: Test ${{ parameters.platform }} ${{ parameters.configuration }}
+- job: Test${{ parameters.platform }}${{ parameters.configuration }}${{ parameters.jobSuffix }}
+  displayName: Test ${{ parameters.platform }} ${{ parameters.configuration }}${{ parameters.jobSuffix }}
   timeoutInMinutes: 300
   variables:
     ${{ if or(eq(parameters.platform, 'x64Win10'), eq(parameters.platform, 'x64Win11')) }}:
@@ -95,28 +113,80 @@ jobs:
       & '$(build.sourcesdirectory)\.pipelines\InstallWinAppDriver.ps1'
     displayName: Download and install WinAppDriver
 
+  - ${{ if eq(parameters.useLatestOfficialBuild, true) }}:
+    - task: DownloadPipelineArtifact@2
+      inputs:
+        buildType: 'specific'
+        project: 'Dart'
+        definition: '76541'
+        buildVersionToDownload: 'latestFromBranch'
+        ${{ if eq(parameters.useCurrentBranchBuild, true) }}:
+          branchName: '$(Build.SourceBranch)'
+        ${{ else }}:
+          branchName: 'refs/heads/main'
+        artifactName: 'build-$(BuildPlatform)-Release'
+        targetPath: '$(Build.ArtifactStagingDirectory)'
+        ${{ if eq(parameters.installMode, 'peruser') }}:
+          patterns: |
+            **/PowerToysUserSetup*.exe
+        ${{ else }}:
+          patterns: |
+            **/PowerToysSetup*.exe
+
+  - ${{ if eq(parameters.useLatestOfficialBuild, true) }}:
+    - ${{ if eq(parameters.installMode, 'peruser') }}:
+      - pwsh: |-
+          & "$(build.sourcesdirectory)\.pipelines\installPowerToys.ps1" -InstallMode "PerUser"
+        displayName: Install PowerToys (Per-User)
+
+    - ${{ if eq(parameters.installMode, 'machine') }}:
+      - pwsh: |-
+          & "$(build.sourcesdirectory)\.pipelines\installPowerToys.ps1" -InstallMode "Machine"
+        displayName: Install PowerToys (Machine-Level)
+
   - ${{ if ne(parameters.platform, 'arm64') }}:
     - task: ScreenResolutionUtility@1
       inputs:
         displaySettings: 'optimal'
 
-  - task: VSTest@3
-    displayName: Run UI Tests
-    inputs:
-      platform: '$(BuildPlatform)'
-      configuration: '$(BuildConfiguration)'
-      testSelector: 'testAssemblies'
-      searchFolder: '$(Pipeline.Workspace)\$(TestArtifactsName)'
-      vsTestVersion: 'toolsInstaller'
-      uiTests: true
-      rerunFailedTests: true
-      # Since UITests-FancyZonesEditor.dll is generated in both UITests-FancyZonesEditor and UITests-FancyZones, removed one to avoid duplicate test runs
-      testAssemblyVer2: |
-        **\*UITest*.dll
-        !**\obj\**
-        !**\ref\**
-        !**\UITests-FancyZones\**\UITests-FancyZonesEditor.dll
+  - ${{ if eq(length(parameters.uiTestModules), 0) }}:
+    - task: VSTest@3
+      displayName: Run UI Tests
+      inputs:
+        platform: '$(BuildPlatform)'
+        configuration: '$(BuildConfiguration)'
+        testSelector: 'testAssemblies'
+        searchFolder: '$(Pipeline.Workspace)\$(TestArtifactsName)'
+        vsTestVersion: 'toolsInstaller'
+        uiTests: true
+        rerunFailedTests: true
+        # Since UITests-FancyZonesEditor.dll is generated in both UITests-FancyZonesEditor and UITests-FancyZones, removed one to avoid duplicate test runs
+        testAssemblyVer2: |
+          **\*UITest*.dll
+          !**\obj\**
+          !**\ref\**
+          !**\UITests-FancyZones\**\UITests-FancyZonesEditor.dll
+      env:
+        platform: '$(TestPlatform)'
+        useInstallerForTest: ${{ parameters.useLatestOfficialBuild }}
 
-
-    env:
-      platform: '$(TestPlatform)'
+  - ${{ if ne(length(parameters.uiTestModules), 0) }}:
+    - ${{ each module in parameters.uiTestModules }}:
+      - task: VSTest@3
+        displayName: Run UI Test - ${{ module }}
+        inputs:
+          platform: '$(BuildPlatform)'
+          configuration: '$(BuildConfiguration)'
+          testSelector: 'testAssemblies'
+          searchFolder: '$(Pipeline.Workspace)\$(TestArtifactsName)'
+          vsTestVersion: 'toolsInstaller'
+          uiTests: true
+          rerunFailedTests: true
+          testAssemblyVer2: |
+            **\*${{ module }}*.dll
+            !**\obj\**
+            !**\ref\**
+            !**\UITests-FancyZones\**\UITests-FancyZonesEditor.dll
+        env:
+          platform: '$(TestPlatform)'
+          useInstallerForTest: ${{ parameters.useLatestOfficialBuild }}

.pipelines/v2/templates/pipeline-ui-tests-automation.yml

@@ -22,63 +22,154 @@ parameters:
   - name: useLatestWebView2
     type: boolean
     default: false
+  - name: useLatestOfficialBuild
+    type: boolean
+    default: true
+  - name: testBothInstallModes
+    type: boolean
+    default: true
+  - name: useCurrentBranchBuild
+    type: boolean
+    default: false
+  - name: uiTestModules
+    type: object
+    default: []
 
 stages:
   - ${{ each platform in parameters.buildPlatforms }}:
-    - stage: Build_${{ platform }}
-      displayName: Build ${{ platform }}
-      dependsOn: []
-      jobs:
-        - template: job-build-project.yml
-          parameters:
-            pool:
-              ${{ if eq(variables['System.CollectionId'], 'cb55739e-4afe-46a3-970f-1b49d8ee7564') }}:
-                name: SHINE-INT-L
-              ${{ else }}:
-                name: SHINE-OSS-L
-              ${{ if eq(parameters.useVSPreview, true) }}:
-                demands: ImageOverride -equals SHINE-VS17-Preview
-            buildPlatforms:
-              - ${{ platform }}
-            buildConfigurations: [Release]
-            enablePackageCaching: true
-            enableMsBuildCaching: ${{ parameters.enableMsBuildCaching }}
-            runTests: false
-            buildTests: true
-            useVSPreview: ${{ parameters.useVSPreview }}
+    - ${{ if eq(parameters.useLatestOfficialBuild, false) }}:
+      - stage: Build_${{ platform }}
+        displayName: Build ${{ platform }}
+        dependsOn: []
+        jobs:
+          - template: job-build-project.yml
+            parameters:
+              pool:
+                ${{ if eq(variables['System.CollectionId'], 'cb55739e-4afe-46a3-970f-1b49d8ee7564') }}:
+                  name: SHINE-INT-L
+                ${{ else }}:
+                  name: SHINE-OSS-L
+                ${{ if eq(parameters.useVSPreview, true) }}:
+                  demands: ImageOverride -equals SHINE-VS17-Preview
+              buildPlatforms:
+                - ${{ platform }}
+              buildConfigurations: [Release]
+              enablePackageCaching: true
+              enableMsBuildCaching: ${{ parameters.enableMsBuildCaching }}
+              runTests: false
+              buildTests: true
+              useVSPreview: ${{ parameters.useVSPreview }}
+
+    - ${{ if eq(parameters.useLatestOfficialBuild, true) }}:
+      - stage: BuildUITests_${{ platform }}
+        displayName: Build UI Tests Only
+        dependsOn: []
+        jobs:
+          - template: job-build-ui-tests.yml
+            parameters:
+              pool:
+                ${{ if eq(variables['System.CollectionId'], 'cb55739e-4afe-46a3-970f-1b49d8ee7564') }}:
+                  name: SHINE-INT-L
+                ${{ else }}:
+                  name: SHINE-OSS-L
+                ${{ if eq(parameters.useVSPreview, true) }}:
+                  demands: ImageOverride -equals SHINE-VS17-Preview
+              buildPlatforms:
+                - ${{ platform }}
+              uiTestModules: ${{ parameters.uiTestModules }}
 
     - ${{ if eq(platform, 'x64') }}:
       - stage: Test_x64Win10
         displayName: Test x64Win10
-        dependsOn:
-          - Build_${{platform}}
+        ${{ if eq(parameters.useLatestOfficialBuild, true) }}:
+          dependsOn:
+            - BuildUITests_${{ platform }}
+        ${{ else }}:
+          dependsOn:
+            - Build_${{ platform }}
         jobs:
             - template: job-test-project.yml
               parameters:
                 platform: x64Win10
                 configuration: Release
                 useLatestWebView2: ${{ parameters.useLatestWebView2 }}
+                useLatestOfficialBuild: ${{ parameters.useLatestOfficialBuild }}
+                useCurrentBranchBuild: ${{ parameters.useCurrentBranchBuild }}
+                uiTestModules: ${{ parameters.uiTestModules }}
+
+            # Additional per-user installation test (when both modes are enabled)
+            - ${{ if and(eq(parameters.useLatestOfficialBuild, true), eq(parameters.testBothInstallModes, true)) }}:
+              - template: job-test-project.yml
+                parameters:
+                  platform: x64Win10
+                  configuration: Release
+                  useLatestWebView2: ${{ parameters.useLatestWebView2 }}
+                  useLatestOfficialBuild: ${{ parameters.useLatestOfficialBuild }}
+                  useCurrentBranchBuild: ${{ parameters.useCurrentBranchBuild }}
+                  uiTestModules: ${{ parameters.uiTestModules }}
+                  installMode: 'peruser'
+                  jobSuffix: '_PerUser'
 
     - ${{ if eq(platform, 'x64') }}:
       - stage: Test_x64Win11
         displayName: Test x64Win11
-        dependsOn:
-          - Build_${{platform}}
+        ${{ if eq(parameters.useLatestOfficialBuild, true) }}:
+          dependsOn:
+            - BuildUITests_${{ platform }}
+        ${{ else }}:
+          dependsOn:
+            - Build_${{ platform }}
         jobs:
             - template: job-test-project.yml
               parameters:
                 platform: x64Win11
                 configuration: Release
                 useLatestWebView2: ${{ parameters.useLatestWebView2 }}
+                useLatestOfficialBuild: ${{ parameters.useLatestOfficialBuild }}
+                useCurrentBranchBuild: ${{ parameters.useCurrentBranchBuild }}
+                uiTestModules: ${{ parameters.uiTestModules }}
+
+            # Additional per-user installation test (when both modes are enabled)
+            - ${{ if and(eq(parameters.useLatestOfficialBuild, true), eq(parameters.testBothInstallModes, true)) }}:
+              - template: job-test-project.yml
+                parameters:
+                  platform: x64Win11
+                  configuration: Release
+                  useLatestWebView2: ${{ parameters.useLatestWebView2 }}
+                  useLatestOfficialBuild: ${{ parameters.useLatestOfficialBuild }}
+                  useCurrentBranchBuild: ${{ parameters.useCurrentBranchBuild }}
+                  uiTestModules: ${{ parameters.uiTestModules }}
+                  installMode: 'peruser'
+                  jobSuffix: '_PerUser'
 
     - ${{ if ne(platform, 'x64') }}:
       - stage: Test_${{ platform }}
         displayName: Test ${{ platform }}
-        dependsOn:
-          - Build_${{platform}}
+        ${{ if eq(parameters.useLatestOfficialBuild, true) }}:
+          dependsOn:
+            - BuildUITests_${{ platform }}
+        ${{ else }}:
+          dependsOn:
+            - Build_${{ platform }}
         jobs:
           - template: job-test-project.yml
             parameters:
               platform: ${{ platform }}
               configuration: Release
               useLatestWebView2: ${{ parameters.useLatestWebView2 }}
+              useLatestOfficialBuild: ${{ parameters.useLatestOfficialBuild }}
+              useCurrentBranchBuild: ${{ parameters.useCurrentBranchBuild }}
+              uiTestModules: ${{ parameters.uiTestModules }}
+
+          # Additional per-user installation test (when both modes are enabled)
+          - ${{ if and(eq(parameters.useLatestOfficialBuild, true), eq(parameters.testBothInstallModes, true)) }}:
+            - template: job-test-project.yml
+              parameters:
+                platform: ${{ platform }}
+                configuration: Release
+                useLatestWebView2: ${{ parameters.useLatestWebView2 }}
+                useLatestOfficialBuild: ${{ parameters.useLatestOfficialBuild }}
+                useCurrentBranchBuild: ${{ parameters.useCurrentBranchBuild }}
+                uiTestModules: ${{ parameters.uiTestModules }}
+                installMode: 'peruser'
+                jobSuffix: '_PerUser'