Initial commit

2025-11-30 08:29:23 +08:00
commit 7c86b87be6
6 changed files with 1822 additions and 0 deletions
--- a/skills/vitest-3-features.md
+++ b/skills/vitest-3-features.md
@@ -0,0 +1,565 @@
+## 🚨 CRITICAL GUIDELINES
+
+### Windows File Path Requirements
+
+**MANDATORY: Always Use Backslashes on Windows for File Paths**
+
+When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
+
+**Examples:**
+- ❌ WRONG: `D:/repos/project/file.tsx`
+- ✅ CORRECT: `D:\repos\project\file.tsx`
+
+This applies to:
+- Edit tool file_path parameter
+- Write tool file_path parameter
+- All file operations on Windows systems
+
+### Documentation Guidelines
+
+**NEVER create new documentation files unless explicitly requested by the user.**
+
+- **Priority**: Update existing README.md files rather than creating new documentation
+- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
+- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
+- **User preference**: Only create additional .md files when user specifically asks for documentation
+
+---
+
+
+# Vitest 3.x Features and Best Practices (2025)
+
+## Overview
+
+Vitest 3.0 was released in January 2025 with major improvements to reporting, browser testing, watch mode, and developer experience. This skill provides comprehensive knowledge of Vitest 3.x features and modern testing patterns.
+
+## Major Features in Vitest 3.0+
+
+### 1. Annotation API (Vitest 3.2+)
+
+The annotation API allows you to add custom metadata, messages, and attachments to any test, visible in UI, HTML, JUnit, TAP, and GitHub Actions reporters.
+
+**Usage:**
+```javascript
+import { test, expect } from 'vitest';
+
+test('user authentication', async ({ task }) => {
+  // Add custom annotation
+  task.meta.annotation = {
+    message: 'Testing OAuth2 flow with external provider',
+    attachments: [
+      { name: 'config', content: JSON.stringify(oauthConfig) }
+    ]
+  };
+
+  const result = await authenticateUser(credentials);
+  expect(result.token).toBeDefined();
+});
+```
+
+**Use Cases:**
+- Document complex test scenarios
+- Attach debug information
+- Link to external resources (tickets, docs)
+- Add performance metrics
+- Track test metadata for reporting
+
+### 2. Line Number Filtering
+
+Run specific tests by their line number in the file, enabling precise test execution from IDEs.
+
+**CLI Usage:**
+```bash
+# Run test at specific line
+vitest run tests/user.test.js:42
+
+# Run multiple tests by line
+vitest run tests/user.test.js:42 tests/user.test.js:67
+
+# Works with ranges
+vitest run tests/user.test.js:42-67
+```
+
+**IDE Integration:**
+- VS Code: Click line number gutter
+- JetBrains IDEs: Run from context menu
+- Enables "run test at cursor" functionality
+
+### 3. Enhanced Watch Mode
+
+Smarter and more responsive watch mode with improved change detection.
+
+**Features:**
+- Detects changes more accurately
+- Only re-runs affected tests
+- Faster rebuild times
+- Better file watching on Windows
+- Reduced false positives
+
+**Configuration:**
+```javascript
+export default defineConfig({
+  test: {
+    watch: true,
+    watchExclude: ['**/node_modules/**', '**/dist/**'],
+    // New in 3.0: More intelligent caching
+    cache: {
+      dir: '.vitest/cache'
+    }
+  }
+});
+```
+
+### 4. Improved Test Reporting
+
+Complete overhaul of test run reporting with reduced flicker and clearer output.
+
+**Reporter API Changes:**
+```javascript
+// Custom reporter with new lifecycle
+export default class CustomReporter {
+  onInit(ctx) {
+    // Called once at start
+  }
+
+  onTestStart(test) {
+    // More reliable test start hook
+  }
+
+  onTestComplete(test) {
+    // Includes full test metadata
+  }
+
+  onFinished(files, errors) {
+    // Final results with all context
+  }
+}
+```
+
+**Benefits:**
+- Less terminal flicker during test runs
+- Clearer test status indicators
+- Better error formatting
+- Improved progress tracking
+
+### 5. Workspace Configuration Simplification
+
+No need for separate workspace files - define projects directly in config.
+
+**Old Way (Vitest 2.x):**
+```javascript
+// vitest.workspace.js
+export default ['packages/*'];
+```
+
+**New Way (Vitest 3.0):**
+```javascript
+// vitest.config.js
+export default defineConfig({
+  test: {
+    workspace: [
+      {
+        test: {
+          name: 'unit',
+          include: ['tests/unit/**/*.test.js']
+        }
+      },
+      {
+        test: {
+          name: 'integration',
+          include: ['tests/integration/**/*.test.js']
+        }
+      }
+    ]
+  }
+});
+```
+
+### 6. Enhanced Browser Testing
+
+Improved browser mode with better performance and caching.
+
+**Multiple Browser Instances:**
+```javascript
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      instances: [
+        { browser: 'chromium', name: 'chrome' },
+        { browser: 'firefox', name: 'ff' },
+        { browser: 'webkit', name: 'safari' }
+      ]
+    }
+  }
+});
+```
+
+**Benefits:**
+- Single Vite server for all browsers
+- Cached file processing
+- Parallel browser execution
+- Reduced startup time
+
+### 7. Improved Coverage
+
+Automatic exclusion of test files from coverage reports.
+
+**Automatic Exclusions (Vitest 3.0):**
+```javascript
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8',
+      // Test files automatically excluded
+      // No need to manually exclude *.test.js
+      exclude: [
+        // Only need to specify custom exclusions
+        '**/node_modules/**',
+        '**/dist/**'
+      ]
+    }
+  }
+});
+```
+
+### 8. Enhanced Mocking
+
+New spy reuse and powerful matchers.
+
+**Spy Reuse:**
+```javascript
+const spy = vi.fn();
+
+// Vitest 3.0: Reuse spy on already mocked method
+vi.spyOn(obj, 'method').mockImplementation(spy);
+vi.spyOn(obj, 'method'); // Reuses existing spy
+```
+
+**New Matchers:**
+```javascript
+// toHaveBeenCalledExactlyOnceWith
+expect(mockFn).toHaveBeenCalledExactlyOnceWith(arg1, arg2);
+
+// Ensures called exactly once with exact arguments
+// Fails if called 0 times, 2+ times, or with different args
+```
+
+### 9. Project Exclusion Patterns
+
+Exclude specific projects using negative patterns.
+
+**CLI Usage:**
+```bash
+# Run all except integration tests
+vitest run --project=!integration
+
+# Run all except multiple projects
+vitest run --project=!integration --project=!e2e
+
+# Combine inclusion and exclusion
+vitest run --project=unit --project=!slow
+```
+
+### 10. UI Improvements
+
+Significantly enhanced test UI with better debugging and navigation.
+
+**New UI Features:**
+- Run individual tests from UI
+- Automatic scroll to failed tests
+- Toggleable node_modules visibility
+- Improved filtering and search
+- Better test management controls
+- Module graph visualization
+
+**Launch UI:**
+```bash
+vitest --ui
+```
+
+## Best Practices for Vitest 3.x
+
+### 1. Use Annotation API for Complex Tests
+
+```javascript
+test('complex payment flow', async ({ task }) => {
+  task.meta.annotation = {
+    message: 'Tests Stripe webhook integration',
+    attachments: [
+      { name: 'webhook-payload', content: JSON.stringify(payload) },
+      { name: 'ticket', content: 'https://jira.company.com/TICKET-123' }
+    ]
+  };
+
+  // Test implementation
+});
+```
+
+### 2. Leverage Line Filtering in Development
+
+```bash
+# Quick iteration on single test
+vitest run src/auth.test.js:145 --watch
+```
+
+### 3. Organize with Workspace Projects
+
+```javascript
+export default defineConfig({
+  test: {
+    workspace: [
+      {
+        test: {
+          name: 'unit-fast',
+          include: ['tests/unit/**/*.test.js'],
+          environment: 'node'
+        }
+      },
+      {
+        test: {
+          name: 'unit-dom',
+          include: ['tests/unit/**/*.dom.test.js'],
+          environment: 'happy-dom'
+        }
+      },
+      {
+        test: {
+          name: 'integration',
+          include: ['tests/integration/**/*.test.js'],
+          setupFiles: ['tests/setup.js']
+        }
+      }
+    ]
+  }
+});
+```
+
+### 4. Use toHaveBeenCalledExactlyOnceWith for Strict Testing
+
+```javascript
+test('should call API exactly once with correct params', () => {
+  const apiSpy = vi.spyOn(api, 'fetchUser');
+
+  renderComponent({ userId: 123 });
+
+  // Strict assertion - fails if called 0, 2+ times or wrong args
+  expect(apiSpy).toHaveBeenCalledExactlyOnceWith(123);
+});
+```
+
+### 5. Optimize Watch Mode for Large Projects
+
+```javascript
+export default defineConfig({
+  test: {
+    watch: true,
+    watchExclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.git/**',
+      '**/coverage/**'
+    ],
+    // Run only related tests
+    changed: true,
+    // Faster reruns
+    isolate: false // Use with caution
+  }
+});
+```
+
+### 6. Custom Reporters for CI/CD
+
+```javascript
+// reporters/junit-plus.js
+export default class JUnitPlusReporter {
+  onFinished(files, errors) {
+    const results = files.map(file => ({
+      name: file.name,
+      tests: file.tasks.length,
+      failures: file.tasks.filter(t => t.result?.state === 'fail').length,
+      // Add annotations from tests
+      annotations: file.tasks
+        .map(t => t.meta?.annotation)
+        .filter(Boolean)
+    }));
+
+    // Export to CI system
+    exportToCI(results);
+  }
+}
+```
+
+```javascript
+// vitest.config.js
+export default defineConfig({
+  test: {
+    reporters: ['default', './reporters/junit-plus.js']
+  }
+});
+```
+
+## Migration from Vitest 2.x to 3.x
+
+### Breaking Changes
+
+1. **Workspace Configuration:**
+   - Move workspace projects into main config
+   - Update project references
+
+2. **Reporter API:**
+   - Update custom reporters to new lifecycle
+   - Check reporter method signatures
+
+3. **Browser Mode:**
+   - Update provider syntax if using browser mode
+   - Review browser configuration
+
+### Migration Steps
+
+```bash
+# Update Vitest
+npm install -D vitest@^3.0.0
+
+# Update related packages
+npm install -D @vitest/ui@^3.0.0
+npm install -D @vitest/coverage-v8@^3.0.0
+
+# Run tests to check for issues
+npm test
+
+# Update configs based on deprecation warnings
+```
+
+## Performance Optimization Tips
+
+### 1. Use Workspace Projects for Isolation
+
+```javascript
+// Separate fast unit tests from slower integration tests
+workspace: [
+  {
+    test: {
+      name: 'unit',
+      include: ['tests/unit/**'],
+      environment: 'node' // Fastest
+    }
+  },
+  {
+    test: {
+      name: 'integration',
+      include: ['tests/integration/**'],
+      environment: 'happy-dom',
+      setupFiles: ['tests/setup.js']
+    }
+  }
+]
+```
+
+### 2. Parallelize Test Execution
+
+```bash
+# Run projects in parallel
+vitest run --project=unit --project=integration
+
+# Exclude slow tests during development
+vitest run --project=!e2e --project=!slow
+```
+
+### 3. Use Line Filtering for TDD
+
+```bash
+# Rapid iteration on single test
+vitest run src/feature.test.js:42 --watch
+```
+
+### 4. Optimize Browser Testing
+
+```javascript
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      // Reuse context for speed (less isolation)
+      isolate: false,
+      // Single instance for development
+      instances: [{ browser: 'chromium' }]
+    }
+  }
+});
+```
+
+## Common Patterns
+
+### Test Annotation for Debugging
+
+```javascript
+test('payment processing', async ({ task }) => {
+  const startTime = Date.now();
+
+  try {
+    const result = await processPayment(data);
+
+    task.meta.annotation = {
+      message: `Completed in ${Date.now() - startTime}ms`,
+      attachments: [
+        { name: 'result', content: JSON.stringify(result) }
+      ]
+    };
+
+    expect(result.success).toBe(true);
+  } catch (error) {
+    task.meta.annotation = {
+      message: 'Payment processing failed',
+      attachments: [
+        { name: 'error', content: error.message },
+        { name: 'payload', content: JSON.stringify(data) }
+      ]
+    };
+    throw error;
+  }
+});
+```
+
+### Multi-Project Testing Strategy
+
+```javascript
+export default defineConfig({
+  test: {
+    workspace: [
+      // Fast feedback loop
+      {
+        test: {
+          name: 'unit-critical',
+          include: ['tests/unit/critical/**'],
+          environment: 'node'
+        }
+      },
+      // Standard tests
+      {
+        test: {
+          name: 'unit-standard',
+          include: ['tests/unit/**'],
+          exclude: ['tests/unit/critical/**'],
+          environment: 'happy-dom'
+        }
+      },
+      // Slow integration tests
+      {
+        test: {
+          name: 'integration',
+          include: ['tests/integration/**'],
+          testTimeout: 30000
+        }
+      }
+    ]
+  }
+});
+```
+
+## Resources
+
+- [Vitest 3.0 Release Notes](https://vitest.dev/blog/vitest-3)
+- [Vitest 3.2 Release Notes](https://vitest.dev/blog/vitest-3-2)
+- [Vitest Documentation](https://vitest.dev/)
+- [Migration Guide](https://vitest.dev/guide/migration.html)
--- a/skills/windows-git-bash-testing.md
+++ b/skills/windows-git-bash-testing.md
@@ -0,0 +1,603 @@
+## 🚨 CRITICAL GUIDELINES
+
+### Windows File Path Requirements
+
+**MANDATORY: Always Use Backslashes on Windows for File Paths**
+
+When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
+
+**Examples:**
+- ❌ WRONG: `D:/repos/project/file.tsx`
+- ✅ CORRECT: `D:\repos\project\file.tsx`
+
+This applies to:
+- Edit tool file_path parameter
+- Write tool file_path parameter
+- All file operations on Windows systems
+
+### Documentation Guidelines
+
+**NEVER create new documentation files unless explicitly requested by the user.**
+
+- **Priority**: Update existing README.md files rather than creating new documentation
+- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
+- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
+- **User preference**: Only create additional .md files when user specifically asks for documentation
+
+---
+
+# 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',
+    video: 'retain-on-failure',
+  },
+  // Output directory with relative path
+  outputDir: './test-results',
+});
+```
+
+## MSW (Mock Service Worker) in Git Bash
+
+MSW generally works without issues in Git Bash, but be aware of:
+
+### 1. Handler File Imports
+
+Use relative imports in MSW setup:
+
+```javascript
+// 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)
+
+Ensure Node.js version 18+ for native Fetch API support:
+
+```bash
+# Check Node version
+node --version  # Should be 18+
+
+# If using older Node, MSW 2.x won't work properly
+```
+
+## Common Windows/Git Bash Test Errors and Fixes
+
+### Error 1: "No such file or directory" in Git Bash
+
+**Symptom:**
+```
+Error: /usr/bin/bash: line 1: C:UsersUsername...No such file
+```
+
+**Cause:** Path conversion issue, often with temp directories.
+
+**Fix:**
+```bash
+# 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
+```
+
+### Error 2: Module Import Failures
+
+**Symptom:**
+```
+Error: Cannot find module '../src/utils'
+```
+
+**Cause:** Path separator confusion (backslash vs forward slash).
+
+**Fix:**
+```javascript
+// 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);
+```
+
+### Error 3: Playwright Browser Launch Failure
+
+**Symptom:**
+```
+Error: Failed to launch browser
+```
+
+**Cause:** Git Bash environment variables interfering with browser launch.
+
+**Fix:**
+```bash
+# Clear problematic environment variables
+unset DISPLAY
+unset BROWSER
+
+# Run Playwright tests
+npx playwright test
+```
+
+### Error 4: Coverage Report Path Issues
+
+**Symptom:**
+```
+Error: Failed to write coverage to /c/project/coverage
+```
+
+**Fix:**
+```javascript
+// vitest.config.js - Use relative paths
+export default defineConfig({
+  test: {
+    coverage: {
+      // ✅ Good
+      reportsDirectory: './coverage',
+
+      // ❌ Bad
+      reportsDirectory: '/c/project/coverage'
+    }
+  }
+});
+```
+
+## Testing Strategy for Multi-Platform Support
+
+### 1. CI/CD Configuration
+
+Test on multiple platforms in CI/CD:
+
+```yaml
+# .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-Specific Test Setup
+
+Create shell-specific setup if needed:
+
+```javascript
+// 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. Path-Safe Test Utilities
+
+Create test utilities that work across all platforms:
+
+```javascript
+// 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');
+```
+
+## Quick Reference
+
+### Shell Detection Commands
+
+```bash
+# 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
+```
+
+### Path Conversion Quick Fixes
+
+```bash
+# 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
+```
+
+### Recommended Test Execution (Git Bash on Windows)
+
+```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
+```
+
+## Resources
+
+- [Git Bash Path Conversion](https://www.msys2.org/docs/filesystem-paths/)
+- [Vitest Configuration](https://vitest.dev/config/)
+- [Playwright on Windows](https://playwright.dev/docs/browsers#install-system-requirements)
+- [MSW Node.js Integration](https://mswjs.io/docs/integrations/node)
+
+## Summary
+
+When running tests on Windows with Git Bash:
+
+1. **Use npm scripts** for all test execution (most reliable)
+2. **Use relative paths** in configuration and imports
+3. **Detect shell environment** when needed for conditional setup
+4. **Disable path conversion** (MSYS_NO_PATHCONV=1) if issues occur
+5. **Test on multiple platforms** in CI/CD to catch platform-specific issues
+6. **Avoid absolute paths** starting with /c/ or C:\ in test files
+7. **Use path.join()** for programmatic path construction
+
+Following these practices ensures tests run reliably across Windows Command Prompt, PowerShell, Git Bash, and Unix-like environments.