windows-git-bash-testing

What this skill does

# Windows and Git Bash Testing Compatibility Guide

## Overview

This guide provides essential knowledge for running Vitest, Playwright, and MSW tests on Windows, particularly in Git Bash/MINGW environments. It addresses common path conversion issues, shell detection, and cross-platform test execution patterns.

## Shell Detection in Test Environments

### Detecting Git Bash/MINGW

When running tests in Git Bash or MINGW environments, use these detection methods:

**Method 1: Environment Variable (Most Reliable)**
```javascript
// 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();
}
```

**Method 2: Using uname in Setup Scripts**
```bash
# 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
```

**Method 3: Combined Detection for Test Configuration**
```javascript
// 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);
```

## Path Conversion Issues and Solutions

### Common Path Conversion Problems

Git Bash automatically converts Unix-style paths to Windows paths, which can cause issues with test file paths, module imports, and test configuration.

**Problem Examples:**
```bash
# 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
```

### Solution 1: Disable Path Conversion

For test commands where path conversion causes issues:

```bash
# 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
```

### Solution 2: Use Native Windows Paths in Configuration

When specifying test file paths in configuration, use Windows-style paths:

```javascript
// 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
    }
  }
});
```

### Solution 3: Path Conversion Helper for Test Utilities

Create a helper for converting paths in test utilities:

```javascript
// 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'));
}
```

**Usage in Tests:**
```javascript
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();
});
```

## Test Execution Best Practices for Windows/Git Bash

### 1. NPM Scripts for Cross-Platform Compatibility

Define test scripts in package.json that work across all environments:

```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"
  }
}
```

**Always use npm scripts rather than direct vitest/playwright commands** - this ensures consistent behavior across shells.

### 2. Relative Path Imports

Use relative paths in test files to avoid path conversion issues:

```javascript
// ✅ 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. Test File Discovery

Vitest and Playwright handle file patterns differently in Git Bash:

```javascript
// 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']
  }
});
```

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

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

### 4. Temporary File Handling

Git Bash uses Unix-style temp directories, which can cause issues:

```javascript
// 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-Specific Windows/Git Bash Considerations

### 1. Browser Installation in Git Bash

```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. Headed Mode in MINGW

When running headed tests in Git Bash, ensure DISPLAY variables are not set:

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

# Run headed tests
npx playwright test --headed
```

### 3. Screenshot and Video Paths

Use relative paths for artifacts:

```javascript
// playwright.config.js
export default defineConfig({
  use: {
    // ✅ Good - Relative paths
    screenshot: 'only-on-failure',
    vid