windows-git-bash-testing

Windows 和 Git Bash 测试兼容性指南

概述

本指南介绍了在 Windows 上运行 Vitest、Playwright 和 MSW 测试所需的知识，尤其适用于 Git Bash/MINGW 环境。指南将介绍常见的路径转换问题、Shell 检测方法，以及跨平台测试执行模式。

测试环境中的 Shell 检测

检测 Git Bash/MINGW

在 Git Bash 或 MINGW 环境中运行测试时，可使用以下检测方法：

方法 1：环境变量（最可靠）

// Detect Git Bash/MINGW in Node.js test setup
function isGitBash() {
  return !!(process.env.MSYSTEM); // MINGW64, MINGW32, MSYS
}

function isWindows() {
  return process.platform === 'win32';
}

function needsPathConversion() {
  return isWindows() && isGitBash();
}

方法 2：在设置脚本中使用 uname

# In bash test setup scripts
case "$(uname -s)" in
  MINGW64*|MINGW32*|MSYS_NT*)
    # Git Bash/MINGW environment
    export TEST_ENV="mingw"
    ;;
  CYGWIN*)
    # Cygwin environment
    export TEST_ENV="cygwin"
    ;;
  Linux*)
    export TEST_ENV="linux"
    ;;
  Darwin*)
    export TEST_ENV="macos"
    ;;
esac

方法 3：在测试配置中组合检测

// vitest.config.js or test setup
import { execSync } from 'child_process';

function detectShell() {
  // Check MSYSTEM first (most reliable for Git Bash)
  if (process.env.MSYSTEM) {
    return { type: 'mingw', subsystem: process.env.MSYSTEM };
  }

  // Try uname if available
  try {
    const uname = execSync('uname -s', { encoding: 'utf8' }).trim();
    if (uname.startsWith('MINGW')) return { type: 'mingw' };
    if (uname.startsWith('CYGWIN')) return { type: 'cygwin' };
    if (uname === 'Darwin') return { type: 'macos' };
    if (uname === 'Linux') return { type: 'linux' };
  } catch {
    // uname not available (likely Windows cmd/PowerShell)
  }

  return { type: 'unknown', platform: process.platform };
}

const shell = detectShell();
console.log('Running tests in:', shell.type);

路径转换问题及解决方案

常见路径转换问题

Git Bash 会自动将 Unix 风格的路径转换为 Windows 路径，这可能导致测试文件路径、模块导入和测试配置出现问题。

问题示例：

# Git Bash converts these automatically:
/foo → C:/Program Files/Git/usr/foo
/foo:/bar → C:\msys64\foo;C:\msys64\bar
--dir=/foo → --dir=C:/msys64/foo

解决方案 1：禁用路径转换

对于路径转换会导致问题的测试命令：

# Disable all path conversion for a single command
MSYS_NO_PATHCONV=1 vitest run

# Disable for specific patterns
export MSYS2_ARG_CONV_EXCL="--coverage.reporter"
vitest run --coverage.reporter=html

# Disable for entire test session
export MSYS_NO_PATHCONV=1
npm test

解决方案 2：在配置中使用原生 Windows 路径

在配置中指定测试文件路径时，请使用 Windows 风格的路径：

// vitest.config.js - Windows-compatible
export default defineConfig({
  test: {
    include: [
      'tests/unit/**/*.test.js',     // Relative paths work best
      'tests/integration/**/*.test.js'
    ],
    // Avoid absolute paths starting with /c/ or C:
    setupFiles: ['./tests/setup.js'], // Use relative paths
    coverage: {
      reportsDirectory: './coverage'  // Relative, not absolute
    }
  }
});

解决方案 3：为测试工具创建路径转换辅助函数

为测试工具创建一个路径转换辅助函数：

// tests/helpers/paths.js
import { execSync } from 'child_process';

/**
 * Convert Windows path to Unix path for Git Bash compatibility
 */
export function toUnixPath(windowsPath) {
  if (!needsPathConversion()) return windowsPath;

  try {
    // Use cygpath if available
    return execSync(`cygpath -u "${windowsPath}"`, {
      encoding: 'utf8'
    }).trim();
  } catch {
    // Fallback: manual conversion
    // C:\Users\foo → /c/Users/foo
    return windowsPath
      .replace(/\\/g, '/')
      .replace(/^([A-Z]):/, (_, drive) => `/${drive.toLowerCase()}`);
  }
}

/**
 * Convert Unix path to Windows path
 */
export function toWindowsPath(unixPath) {
  if (!needsPathConversion()) return unixPath;

  try {
    return execSync(`cygpath -w "${unixPath}"`, {
      encoding: 'utf8'
    }).trim();
  } catch {
    // Fallback: manual conversion
    // /c/Users/foo → C:\Users\foo
    return unixPath
      .replace(/^\/([a-z])\//, (_, drive) => `${drive.toUpperCase()}:\\`)
      .replace(/\//g, '\\');
  }
}

function needsPathConversion() {
  return !!(process.env.MSYSTEM ||
           (process.platform === 'win32' && process.env.TERM === 'cygwin'));
}

在测试中的用法：

import { toUnixPath, toWindowsPath } from '../helpers/paths.js';

test('loads config file', () => {
  const configPath = toWindowsPath('/c/project/config.json');
  const config = loadConfig(configPath);
  expect(config).toBeDefined();
});

Windows/Git Bash 测试执行最佳实践

1. 使用 NPM 脚本确保跨平台兼容性

在 package.json 中定义可在所有环境下运行的测试脚本：

{
  "scripts": {
    "test": "vitest run",
    "test:unit": "vitest run tests/unit",
    "test:integration": "vitest run tests/integration",
    "test:watch": "vitest watch",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "playwright test",
    "test:e2e:headed": "playwright test --headed",
    "test:debug": "vitest run --reporter=verbose"
  }
}

始终使用 npm 脚本，而不要直接运行 vitest/playwright 命令——这样可以确保在不同 Shell 中行为一致。

2. 使用相对路径导入

在测试文件中使用相对路径，以避免路径转换问题：

// ✅ Good - Relative paths work everywhere
import { myFunction } from '../../src/utils.js';
import { server } from '../mocks/server.js';

// ❌ Bad - Absolute paths can cause issues in Git Bash
import { myFunction } from '/c/project/src/utils.js';

3. 测试文件发现

Vitest 和 Playwright 在 Git Bash 中处理文件模式的方式不同：

// vitest.config.js - Use glob patterns, not absolute paths
export default defineConfig({
  test: {
    // ✅ Good - Glob patterns work cross-platform
    include: ['tests/**/*.test.js', 'src/**/*.test.js'],

    // ❌ Bad - Absolute paths problematic in Git Bash
    include: ['/c/project/tests/**/*.test.js']
  }
});

// playwright.config.js - Relative directory paths
export default defineConfig({
  // ✅ Good
  testDir: './tests/e2e',

  // ❌ Bad
  testDir: '/c/project/tests/e2e'
});

4. 临时文件处理

Git Bash 使用 Unix 风格的临时目录，这可能导致问题：

// tests/setup.js - Cross-platform temp file handling
import os from 'os';
import path from 'path';

function getTempDir() {
  const tmpdir = os.tmpdir();

  // In Git Bash, os.tmpdir() may return Windows path
  // Ensure it's usable by your test framework
  if (process.env.MSYSTEM && !tmpdir.startsWith('/')) {
    // Convert Windows temp path if needed
    return tmpdir.replace(/\\/g, '/');
  }

  return tmpdir;
}

// Use in tests
const testTempDir = path.join(getTempDir(), 'my-tests');

Playwright 在 Windows/Git Bash 中的注意事项

1. 在 Git Bash 中安装浏览器

# Use npx to ensure correct path handling
npx playwright install

# If issues occur, use Windows-native command prompt instead
# Then run tests from Git Bash

2. 在 MINGW 中运行有头模式

在 Git Bash 中运行有头测试时，请确保未设置 DISPLAY 变量：

# Unset DISPLAY if set (can interfere with Windows GUI)
unset DISPLAY

# Run headed tests
npx playwright test --headed

3. 截图和视频路径

请为测试产物使用相对路径：

// playwright.config.js
export default defineConfig({
  use: {
    // ✅ Good - Relative paths
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  // Output directory with relative path
  outputDir: './test-results',
});

在 Git Bash 中使用 MSW（Mock Service Worker）

MSW 通常可以在 Git Bash 中正常运行，但请注意以下事项：

1. 处理程序文件导入

在 MSW 设置中使用相对导入：

// tests/mocks/server.js
// ✅ Good
import { handlers } from './handlers.js';

// ❌ Bad - Avoid absolute paths
import { handlers } from '/c/project/tests/mocks/handlers.js';

2. Fetch polyfill（Node.js）

请使用 Node.js 18+ 版本，以支持原生 Fetch API：

# Check Node version
node --version  # Should be 18+

# If using older Node, MSW 2.x won't work properly

常见 Windows/Git Bash 测试错误及修复方法

错误 1：Git Bash 中出现“找不到文件或目录”

症状：

Error: /usr/bin/bash: line 1: C:UsersUsername...No such file

原因： 路径转换问题，通常与临时目录有关。

修复方法：

# Option 1: Disable path conversion
MSYS_NO_PATHCONV=1 npm test

# Option 2: Use Claude Code's Git Bash path variable
export CLAUDE_CODE_GIT_BASH_PATH="C:\\Program Files\\git\\bin\\bash.exe"

# Option 3: Run via npm scripts (recommended)
npm test  # npm handles path issues automatically

错误 2：模块导入失败

症状：

Error: Cannot find module '../src/utils'

原因： 路径分隔符混淆（反斜杠与正斜杠）。

修复方法：

// Use path.join() or path.resolve() for cross-platform paths
import path from 'path';

const utilsPath = path.resolve(__dirname, '../src/utils.js');
const utils = await import(utilsPath);

错误 3：Playwright 浏览器启动失败

症状：

Error: Failed to launch browser

原因： Git Bash 环境变量干扰了浏览器启动。

修复方法：

# Clear problematic environment variables
unset DISPLAY
unset BROWSER

# Run Playwright tests
npx playwright test

错误 4：覆盖率报告路径问题

症状：

Error: Failed to write coverage to /c/project/coverage

修复方法：

// vitest.config.js - Use relative paths
export default defineConfig({
  test: {
    coverage: {
      // ✅ Good
      reportsDirectory: './coverage',

      // ❌ Bad
      reportsDirectory: '/c/project/coverage'
    }
  }
});

多平台支持测试策略

1. CI/CD 配置

在 CI/CD 中针对多个平台进行测试：

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

      - run: npm ci
      - run: npm test
      - run: npm run test:e2e
        if: matrix.os == 'ubuntu-latest'  # Run E2E on Linux only

2. 特定 Shell 的测试设置

如有需要，请创建特定 Shell 的设置：

// tests/setup.js
import { detectShell } from './helpers/shell-detect.js';

const shell = detectShell();

// Apply shell-specific configuration
if (shell.type === 'mingw') {
  console.log('Running in Git Bash/MINGW environment');
  // Apply MINGW-specific test setup
  process.env.FORCE_COLOR = '1'; // Enable colors in Git Bash
}

// Standard setup continues...

3. 路径安全的测试工具

创建可在所有平台上运行的测试工具：

// tests/helpers/test-utils.js
import path from 'path';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

// Get __dirname equivalent in ESM
export function getCurrentDir(importMetaUrl) {
  return dirname(fileURLToPath(importMetaUrl));
}

// Cross-platform path joining
export function testPath(...segments) {
  return path.join(...segments).replace(/\\/g, '/');
}

// Usage in test file:
// const __dirname = getCurrentDir(import.meta.url);
// const fixturePath = testPath(__dirname, 'fixtures', 'data.json');

快速参考

Shell 检测命令

# Check if running in Git Bash
echo $MSYSTEM           # MINGW64, MINGW32, or empty

# Check OS type
uname -s               # MINGW64_NT-* for Git Bash

# Check platform in Node
node -p process.platform  # win32 on Windows

路径转换快速修复方法

# Disable for single command
MSYS_NO_PATHCONV=1 vitest run

# Disable for session
export MSYS_NO_PATHCONV=1

# Convert path manually
cygpath -u "C:\path"    # Windows → Unix
cygpath -w "/c/path"    # Unix → Windows

推荐的测试执行方式（Windows 上的 Git Bash）

# ✅ Best - Use npm scripts
npm test
npm run test:e2e

# ✅ Good - With path conversion disabled
MSYS_NO_PATHCONV=1 vitest run

# ⚠️ Caution - Direct vitest command may have issues
vitest run  # May encounter path conversion issues

资源

• Git Bash 路径转换
• Vitest 配置
• Windows 上的 Playwright
• MSW Node.js 集成

总结

在 Windows 上使用 Git Bash 运行测试时：

1. 使用 npm 脚本执行所有测试（最可靠）
2. 在配置和导入中使用相对路径
3. 必要时检测 Shell 环境，以进行条件设置
4. 如果出现问题，禁用路径转换（MSYS_NO_PATHCONV=1）
5. 在 CI/CD 中在多个平台上测试，以发现平台特定问题
6. 避免在测试文件中使用以 /c/ 或 C:\ 开头的绝对路径
7. **使用 path.join()**以编程方式构建路径

遵循这些做法可确保测试在 Windows 命令提示符、PowerShell、Git Bash 和类 Unix 环境中可靠运行。