feat(qa): 实现 Windows 上 QA 提速与降噪设计

- 新增 `test:qa` 命令，采用固定 smoke 测试集与变更感知策略
- 修复 package.json 中 PowerShell 环境变量转义问题
- 在 qa.mjs 中实现变更文件收集与测试路径映射
- 更新 Pester 配置以支持 qa 模式，排除慢测与噪音
- 将 `qa:pwsh` 命令切换为使用新的 `test:qa` 模式

Author: mudssky

PesterConfiguration.ps1

@@ -34,17 +34,36 @@ if ($IsLinux -or $IsMacOS) {
 
 
 $isCI = [bool]$env:CI
-$testMode = if ([string]::IsNullOrWhiteSpace($env:PWSH_TEST_MODE)) { 'full' } else { $env:PWSH_TEST_MODE }
-$isFast = $testMode -in @('fast', 'serial', 'debug')
+$testMode = if ([string]::IsNullOrWhiteSpace($env:PWSH_TEST_MODE)) { 'full' } else { $env:PWSH_TEST_MODE.Trim().ToLowerInvariant() }
+$isQa = $testMode -eq 'qa'
+$isFast = $testMode -in @('fast', 'serial', 'debug', 'qa')
 $isSerial = $testMode -eq 'serial'
 $isDebug = $testMode -eq 'debug'
 $isVerbose = -not [string]::IsNullOrWhiteSpace($env:PWSH_TEST_VERBOSE)
 
-$runPaths = @("./psutils", "./tests")
+$qaDefaultPaths = @(
+    "./tests/DeferredLoading.Tests.ps1"
+    "./tests/losslessToAdaptiveAudio.Tests.ps1"
+    "./tests/ProfileMode.Tests.ps1"
+    "./tests/Switch-Mirrors.Tests.ps1"
+    "./psutils/tests/error.Tests.ps1"
+    "./psutils/tests/filesystem.Tests.ps1"
+    "./psutils/tests/font.Tests.ps1"
+    "./psutils/tests/git.Tests.ps1"
+    "./psutils/tests/string.Tests.ps1"
+    "./psutils/tests/win.Tests.ps1"
+    "./psutils/tests/wrapper.Tests.ps1"
+)
+
+$runPaths = if ($isQa) { $qaDefaultPaths } else { @("./psutils", "./tests") }
 if (-not [string]::IsNullOrWhiteSpace($env:PWSH_TEST_PATH)) {
     $runPaths = $env:PWSH_TEST_PATH -split '[;,]' | ForEach-Object { $_.Trim() } | Where-Object { $_ }
 }
 
+if ($isQa) {
+    $excludeTags += 'QaSkip'
+}
+
 $config = @{
     Run          = @{
         Path     = $runPaths

docs/plans/2026-03-05-qa-speed-design.md

@@ -0,0 +1,44 @@
+# QA 提速与降噪设计（Windows）
+
+## 背景
+- 现状 `pnpm qa` 在 Windows 上会触发大量慢测与噪音输出，耗时远超本地快速反馈目标。
+- `test:fast` 存在环境变量转义问题，导致模式未生效，实际执行接近全量。
+
+## 目标
+- 本地 `pnpm qa` 目标耗时尽量控制在 20 秒以内。
+- 输出保留“每个测试文件耗时 + 错误/失败 + 汇总”，减少无关噪音。
+- 慢测从 `qa` 中剥离，保留在 `test:fast`/`test:full` 或 CI 场景执行。
+
+## 设计
+### 1) 命令分层
+- 新增 `test:qa`（`PWSH_TEST_MODE=qa`）。
+- `qa:pwsh` 从 `test:fast` 切换为 `test:qa`。
+- 修复 `test:fast/full/serial/debug` 的 PowerShell 环境变量转义。
+
+### 2) 测试集策略
+- `qa` 采用“固定 smoke + changed-aware”策略：
+  - 固定 smoke：一组低耗时基础测试，始终执行。
+  - changed-aware：根据改动文件追加相关测试。
+- 显式排除已知慢/高噪音测试文件，避免本地质量门被拖慢。
+
+### 3) 调度实现
+- 在 `scripts/qa.mjs` 增加：
+  - 变更文件收集（工作区、暂存区、未跟踪 + 与基线对比）。
+  - 路径映射规则（`psutils/modules/<name>.psm1 -> psutils/tests/<name>.Tests.ps1`）。
+  - `PWSH_TEST_PATH` 注入 `qa:pwsh`，由 Pester 只执行目标子集。
+
+### 4) Pester 模式
+- `PesterConfiguration.ps1` 增加 `qa` 模式：
+  - 默认 `Run.Path` 使用 smoke 集合；
+  - 支持 `PWSH_TEST_PATH` 覆盖；
+  - 关闭 CodeCoverage；
+  - 保持 `Output.Verbosity='Normal'`。
+
+## 风险与权衡
+- 风险：`qa` 覆盖面降低可能漏检非 smoke 问题。
+- 缓解：保留 `test:fast`/`test:full` 作为更全面验证入口，CI 中继续执行更重测试。
+
+## 验证标准
+- `pnpm qa` 在常见变更场景下显著低于历史耗时。
+- `pnpm qa` 输出仍包含文件级耗时与失败摘要。
+- `pnpm test:fast` 环境变量生效，不再出现 `\$env:` 解释错误。

package.json

@@ -21,13 +21,14 @@
     "pester:install": "pwsh -NoProfile -Command \"Install-Module -Name Pester -Scope CurrentUser -Force -SkipPublisherCheck -AllowClobber\"",
     "pester:update": "pwsh -NoProfile -Command \"Update-Module -Name Pester -Force -ErrorAction Stop\"",
     "test": "pwsh -NoProfile -Command \"Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:full": "pwsh -Command \"\\$env:PWSH_TEST_MODE='full'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:fast": "pwsh -NoProfile -Command \"\\$env:PWSH_TEST_MODE='fast'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:serial": "pwsh -NoProfile -Command \"\\$env:PWSH_TEST_MODE='serial'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:debug": "pwsh -NoProfile -Command \"\\$env:PWSH_TEST_MODE='debug'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:serial:debug": "pwsh -NoProfile -Command \"\\$env:PWSH_TEST_MODE='serial'; \\$env:PWSH_TEST_VERBOSE='1'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:profile": "pwsh -NoProfile -Command \"\\$env:PWSH_TEST_MODE='serial'; \\$env:PWSH_TEST_PATH='./tests/ProfileMode.Tests.ps1'; \\$env:PWSH_TEST_VERBOSE='1'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
-    "test:slow": "pwsh -NoProfile -Command \"\\$c = ./PesterConfiguration.ps1; \\$c.Filter.Tag = 'Slow'; \\$c.Filter.ExcludeTag = @(\\$c.Filter.ExcludeTag.Value | Where-Object { \\$_ -ne 'Slow' }); Invoke-Pester -Configuration \\$c\"",
+    "test:full": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='full'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:fast": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='fast'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:qa": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='qa'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:serial": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='serial'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:debug": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='debug'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:serial:debug": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='serial'; $env:PWSH_TEST_VERBOSE='1'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:profile": "pwsh -NoProfile -Command \"$env:PWSH_TEST_MODE='serial'; $env:PWSH_TEST_PATH='./tests/ProfileMode.Tests.ps1'; $env:PWSH_TEST_VERBOSE='1'; Invoke-Pester -Configuration ( ./PesterConfiguration.ps1 )\"",
+    "test:slow": "pwsh -NoProfile -Command \"$c = ./PesterConfiguration.ps1; $c.Filter.Tag = 'Slow'; $c.Filter.ExcludeTag = @($c.Filter.ExcludeTag.Value | Where-Object { $_ -ne 'Slow' }); Invoke-Pester -Configuration $c\"",
     "test:detailed": "pwsh -Command \"Invoke-Pester -Output Detailed\"",
     "scripts:install": "pwsh  -File ./install.ps1",
     "scoop:update": "scoop update -a",
@@ -36,7 +37,7 @@
     "test:linux": "docker compose -f docker-compose.pester.yml run --rm pester-fast",
     "test:linux:full": "docker compose -f docker-compose.pester.yml run --rm pester-full",
     "test:linux:build": "docker compose -f docker-compose.pester.yml build",
-    "qa:pwsh": "pnpm format:pwsh && pnpm test:fast",
+    "qa:pwsh": "pnpm format:pwsh && pnpm test:qa",
     "qa": "node ./scripts/qa.mjs changed",
     "qa:all": "node ./scripts/qa.mjs all",
     "qa:verbose": "node ./scripts/qa.mjs changed --verbose",

scripts/qa.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
 
 class CommandFailedError extends Error {
   constructor(step, command, args, exitCode, spawnError) {
@@ -44,6 +45,30 @@ if (!verbose) {
 }
 
 const supportedModes = new Set(['changed', 'all'])
+const qaSmokeTestPaths = [
+  './tests/DeferredLoading.Tests.ps1',
+  './tests/losslessToAdaptiveAudio.Tests.ps1',
+  './tests/ProfileMode.Tests.ps1',
+  './tests/Switch-Mirrors.Tests.ps1',
+  './psutils/tests/error.Tests.ps1',
+  './psutils/tests/filesystem.Tests.ps1',
+  './psutils/tests/font.Tests.ps1',
+  './psutils/tests/git.Tests.ps1',
+  './psutils/tests/string.Tests.ps1',
+  './psutils/tests/win.Tests.ps1',
+  './psutils/tests/wrapper.Tests.ps1',
+]
+const qaExcludedTestPaths = new Set([
+  './psutils/tests/cache.Tests.ps1',
+  './psutils/tests/hardware.Tests.ps1',
+  './psutils/tests/help.Tests.ps1',
+  './psutils/tests/install.Tests.ps1',
+  './psutils/tests/network.Tests.ps1',
+  './psutils/tests/profile_unix.Tests.ps1',
+  './psutils/tests/profile_windows.Tests.ps1',
+  './psutils/tests/proxy.Tests.ps1',
+  './psutils/tests/test.Tests.ps1',
+])
 
 if (!supportedModes.has(mode)) {
   console.error(`[qa] unsupported mode: ${mode}`)
@@ -72,14 +97,14 @@ function runCommand(step, command, args, options = {}) {
   }
 }
 
-function runPnpm(step, pnpmArgs) {
+function runPnpm(step, pnpmArgs, options = {}) {
   if (runPnpmWithNode) {
-    runCommand(step, process.execPath, [pnpmExecPath, ...pnpmArgs])
+    runCommand(step, process.execPath, [pnpmExecPath, ...pnpmArgs], options)
     return
   }
 
   const command = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
-  runCommand(step, command, pnpmArgs)
+  runCommand(step, command, pnpmArgs, options)
 }
 
 function runCapture(command, args) {
@@ -165,6 +190,119 @@ function hasPathChanges(pathspecs, sinceRef) {
   })
 }
 
+function toRepoPath(pathValue) {
+  return pathValue.replace(/\\/g, '/').replace(/^\.\//, '')
+}
+
+function toQaTestPath(pathValue) {
+  const prefixed = pathValue.startsWith('./') ? pathValue : `./${pathValue}`
+  return prefixed.replace(/\\/g, '/')
+}
+
+function shouldIncludeQaTest(pathValue) {
+  const qaPath = toQaTestPath(pathValue)
+  if (qaExcludedTestPaths.has(qaPath)) {
+    return false
+  }
+  const repoPath = toRepoPath(qaPath)
+  return existsSync(repoPath)
+}
+
+function collectChangedFiles(pathspecs, sinceRef) {
+  const checks = []
+
+  if (sinceRef) {
+    checks.push([
+      'diff',
+      '--name-only',
+      '--diff-filter=ACMRT',
+      `${sinceRef}...HEAD`,
+      '--',
+      ...pathspecs,
+    ])
+  }
+
+  checks.push(['diff', '--name-only', '--diff-filter=ACMRT', '--', ...pathspecs])
+  checks.push([
+    'diff',
+    '--name-only',
+    '--diff-filter=ACMRT',
+    '--cached',
+    '--',
+    ...pathspecs,
+  ])
+  checks.push(['ls-files', '--others', '--exclude-standard', '--', ...pathspecs])
+
+  const changed = new Set()
+
+  for (const args of checks) {
+    const result = runCapture('git', args)
+    if (result.status !== 0 || result.stdout.length === 0) {
+      continue
+    }
+    for (const line of result.stdout.split('\n').filter(Boolean)) {
+      changed.add(toRepoPath(line))
+    }
+  }
+
+  return [...changed]
+}
+
+function addQaTestPath(selected, testPath) {
+  const normalized = toQaTestPath(testPath)
+  if (!shouldIncludeQaTest(normalized)) {
+    if (verbose) {
+      console.log(`[qa:verbose] skip qa test path: ${normalized}`)
+    }
+    return
+  }
+  selected.add(normalized)
+}
+
+function resolveQaTestPaths(modeValue, sinceRef, pathspecs) {
+  const selected = new Set()
+  for (const testPath of qaSmokeTestPaths) {
+    addQaTestPath(selected, testPath)
+  }
+
+  if (modeValue !== 'changed') {
+    return [...selected]
+  }
+
+  const changedFiles = collectChangedFiles(pathspecs, sinceRef)
+  if (verbose) {
+    console.log(`[qa:verbose] root changed files: ${changedFiles.length}`)
+  }
+
+  for (const changedFile of changedFiles) {
+    if (changedFile.startsWith('tests/') && changedFile.endsWith('.Tests.ps1')) {
+      addQaTestPath(selected, changedFile)
+      continue
+    }
+
+    if (
+      changedFile.startsWith('psutils/tests/') &&
+      changedFile.endsWith('.Tests.ps1')
+    ) {
+      addQaTestPath(selected, changedFile)
+      continue
+    }
+
+    if (
+      changedFile.startsWith('psutils/modules/') &&
+      changedFile.endsWith('.psm1')
+    ) {
+      const fileName = changedFile.split('/').pop()
+      const moduleName = fileName?.replace(/\.psm1$/i, '')
+      if (moduleName) {
+        addQaTestPath(selected, `./psutils/tests/${moduleName}.Tests.ps1`)
+      }
+    }
+  }
+
+  return [...selected]
+}
+
 function runWorkspaceQa(modeValue, sinceRef) {
   const recursiveArgs = [
     '-r',
@@ -197,28 +335,43 @@ function runWorkspaceQa(modeValue, sinceRef) {
 }
 
 function runRootPwshQa(modeValue, sinceRef) {
-  if (modeValue === 'all') {
-    console.log('[qa] run root qa:pwsh (all)')
-    runPnpm('root-qa-pwsh-all', ['run', 'qa:pwsh'])
-    return
-  }
-
   const pwshPathspecs = [
     'scripts/pwsh',
     'profile',
     'tests',
+    'psutils/modules',
+    'psutils/tests',
     'PesterConfiguration.ps1',
     'install.ps1',
     'Manage-BinScripts.ps1',
   ]
 
+  const qaTestPaths = resolveQaTestPaths(modeValue, sinceRef, pwshPathspecs)
+  const qaEnv = { ...process.env }
+  if (qaTestPaths.length > 0) {
+    qaEnv.PWSH_TEST_PATH = qaTestPaths.join(';')
+  }
+
+  if (verbose) {
+    console.log(`[qa:verbose] qa test paths (${qaTestPaths.length})`)
+    for (const testPath of qaTestPaths) {
+      console.log(`[qa:verbose]   ${testPath}`)
+    }
+  }
+
+  if (modeValue === 'all') {
+    console.log('[qa] run root qa:pwsh (all)')
+    runPnpm('root-qa-pwsh-all', ['run', 'qa:pwsh'], { env: qaEnv })
+    return
+  }
+
   if (!hasPathChanges(pwshPathspecs, sinceRef)) {
     console.log('[qa] skip root qa:pwsh (no changes)')
     return
   }
 
   console.log('[qa] run root qa:pwsh (changed)')
-  runPnpm('root-qa-pwsh-changed', ['run', 'qa:pwsh'])
+  runPnpm('root-qa-pwsh-changed', ['run', 'qa:pwsh'], { env: qaEnv })
 }
 
 const sinceRef = mode === 'changed' ? resolveSinceRef() : null
@@ -252,4 +405,4 @@ try {
   }
 
   throw error
-}
+}