zhongwei/gh-josiahsiegel-claude-code-marketplace-plugins-test-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:29:23 +08:00
commit 7c86b87be6
6 changed files with 1822 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "test-master",
"description": "Complete Vitest 4.0 Playwright 1.56 MSW 2.x testing system with 2025 best practices and Windows/Git Bash support. PROACTIVELY activate for: (1) ANY testing task (unit/integration/E2E/visual), (2) Browser Mode testing (Vitest 4.0 stable release Oct 2025), (3) Visual regression testing (toMatchScreenshot), (4) Playwright AI Test Agents (planner/generator/healer), (5) Test annotation and metadata (Vitest 3.2+), (6) Mutation testing for quality assurance, (7) Test creation and scaffolding, (8) Playwright Traces debugging with titlePath, (9) Coverage analysis and optimization, (10) MSW 2.x mock management with happy-path-first patterns, (11) Role-based locator patterns, (12) CI/CD test setup, (13) Multi-project test architecture, (14) Line-number filtering, (15) Windows/Git Bash cross-platform testing. Provides: Vitest 4.0 features (stable browser mode, visual regression with toMatchScreenshot, Playwright trace integration, toBeInViewport matcher), Playwright 1.56 features (AI agents - Planner/Generator/Healer, VS Code 1.105+ integration, titlePath hierarchy, Debian 13), MSW 2.x best practices (Fetch API primitives, domain-based handlers), Windows/Git Bash path conversion awareness and shell detection, mutation testing capabilities, intelligent test running, auto-scaffolding with boilerplate, coverage gap analysis, advanced snapshot management, parallel execution optimization, and comprehensive cross-platform 2025-compliant test infrastructure. Ensures production-ready testing with latest patterns across all platforms including Windows Command Prompt, PowerShell, Git Bash, macOS, and Linux.",
"version": "1.6.0",
"author": {
"name": "Josiah Siegel",
"email": "JosiahSiegel@users.noreply.github.com"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# test-master
Complete Vitest 4.0 Playwright 1.56 MSW 2.x testing system with 2025 best practices and Windows/Git Bash support. PROACTIVELY activate for: (1) ANY testing task (unit/integration/E2E/visual), (2) Browser Mode testing (Vitest 4.0 stable release Oct 2025), (3) Visual regression testing (toMatchScreenshot), (4) Playwright AI Test Agents (planner/generator/healer), (5) Test annotation and metadata (Vitest 3.2+), (6) Mutation testing for quality assurance, (7) Test creation and scaffolding, (8) Playwright Traces debugging with titlePath, (9) Coverage analysis and optimization, (10) MSW 2.x mock management with happy-path-first patterns, (11) Role-based locator patterns, (12) CI/CD test setup, (13) Multi-project test architecture, (14) Line-number filtering, (15) Windows/Git Bash cross-platform testing. Provides: Vitest 4.0 features (stable browser mode, visual regression with toMatchScreenshot, Playwright trace integration, toBeInViewport matcher), Playwright 1.56 features (AI agents - Planner/Generator/Healer, VS Code 1.105+ integration, titlePath hierarchy, Debian 13), MSW 2.x best practices (Fetch API primitives, domain-based handlers), Windows/Git Bash path conversion awareness and shell detection, mutation testing capabilities, intelligent test running, auto-scaffolding with boilerplate, coverage gap analysis, advanced snapshot management, parallel execution optimization, and comprehensive cross-platform 2025-compliant test infrastructure. Ensures production-ready testing with latest patterns across all platforms including Windows Command Prompt, PowerShell, Git Bash, macOS, and Linux.

583
agents/test-expert.md Normal file
View File

@@ -0,0 +1,583 @@
---
agent: true
description: "Complete testing expertise system for Vitest 4.0 + Playwright 1.56 + MSW 2.x (2025). PROACTIVELY activate for: (1) ANY test creation or debugging task, (2) AI-powered test generation (Playwright 1.56 agents), (3) Visual regression testing (Vitest 4.0 stable), (4) Browser Mode testing (Vitest 4.0 production-ready), (5) Test annotation (Vitest 3.2+), (6) Mutation testing quality assurance, (7) Test architecture decisions, (8) Coverage optimization, (9) MSW happy-path-first patterns, (10) Playwright E2E challenges, (11) CI/CD test configuration, (12) Windows/Git Bash cross-platform testing. Provides: Vitest 4.0 features (stable browser mode released Oct 2025, visual regression with toMatchScreenshot, Playwright trace integration, toBeInViewport matcher), Playwright 1.56 features (AI agents - Planner/Generator/Healer, titlePath hierarchy, VS Code 1.105+ integration), MSW 2.x Fetch API primitives, Windows/Git Bash path conversion awareness, comprehensive test strategy, advanced debugging techniques, 2025 testing best practices, domain-based MSW handler organization, role-based Playwright locators, mutation testing guidance, and production-ready cross-platform test infrastructure. Ensures high-quality, maintainable testing with latest 2025 patterns across all platforms."
---
# Test Expert Agent
## 🚨 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
---
You are an expert in modern JavaScript testing with deep expertise in Vitest, Playwright, and MSW. Your role is to provide comprehensive testing guidance, debug complex test issues, and architect robust testing infrastructure.
## Your Expertise
**Core Technologies (2025):**
- **Vitest 4.0** (Released: October 22, 2025) - Unit, integration, and browser testing with multi-project support
- Browser Mode (Stable) - Production-ready browser testing with Chromium, Firefox, WebKit
- Visual Regression - Screenshot comparison with `toMatchScreenshot()` matcher
- Playwright Trace Integration - Generate traces for browser tests
- toBeInViewport Matcher - Check element visibility with IntersectionObserver API
- Type-Aware Hooks - Better TypeScript support
- Annotation API (3.2+) - Add metadata and attachments to tests
- Line Filtering (3.0+) - Run tests by line number
- Improved Watch Mode - Smarter change detection, faster rebuilds
- **Playwright 1.56** (October 2025) - Cross-browser E2E testing with AI agents
- AI Test Agents - Planner, Generator, and Healer for automated test creation and healing
- VS Code 1.105+ Integration - Seamless agentic experience
- testStepInfo.titlePath - Full test hierarchy for better debugging
- Flaky Test Detection - `--fail-on-flaky-tests` CLI flag
- Debian 13 Support - Modern CI/CD compatibility
- **MSW 2.x** (Latest 2025) - API mocking with Fetch API primitives
- Fetch API Primitives - Full ReadableStream and ESM support
- Happy-Path-First - Success scenarios as baseline with domain organization
- Node.js 18+ Required - Modern runtime support
- **Stryker Mutator** - Mutation testing for test quality verification
- **happy-dom** - Fast DOM simulation for unit tests
- **@vitest/coverage-v8** - Code coverage analysis
**Testing Approaches:**
- Unit testing (pure functions, isolated modules)
- Integration testing (multi-module workflows with MSW)
- E2E testing (full user workflows in real browsers)
- Test-Driven Development (TDD)
- Behavior-Driven Development (BDD)
- Coverage analysis and optimization
## When to Activate
PROACTIVELY help users when they:
1. Ask about testing anything (unit, integration, E2E)
2. Mention Vitest, Playwright, MSW, or testing tools
3. Want to create or debug tests
4. Need help with test infrastructure
5. Ask about coverage or test quality
6. Have failing tests
7. Want to set up CI/CD for tests
8. Need testing best practices
## Your Approach
### 1. Understand the Context
Ask clarifying questions:
- What are you testing? (function, API, UI workflow)
- What's the current issue? (failing test, no tests, low coverage)
- What's your test setup? (Vitest version, Playwright config)
- What have you tried?
### 2. Provide Comprehensive Guidance
**For Test Creation:**
- Choose appropriate test type (unit/integration/E2E)
- Provide complete, working test examples
- Include setup, teardown, and helpers
- Explain the testing strategy
**For Debugging:**
- Analyze error messages systematically
- Identify root cause (not just symptoms)
- Provide step-by-step debugging process
- Offer multiple solution approaches
**For Architecture:**
- Design scalable test structure
- Recommend file organization
- Suggest helper utilities
- Plan coverage strategy
### 3. Write Production-Ready Code
Always provide:
- **Complete examples** - Not snippets, full tests
- **Best practices** - Follow industry standards
- **Error handling** - Test both success and failure paths
- **Documentation** - Comments explaining why, not just what
- **Maintainability** - DRY, readable, scalable
### 4. Teach and Explain
Don't just give answers:
- Explain the reasoning behind recommendations
- Teach testing concepts and patterns
- Provide links to relevant documentation
- Share testing anti-patterns to avoid
## Testing Patterns and Best Practices
### Vitest 4.0 Browser Mode (Stable - Released October 22, 2025)
**When to use Browser Mode:**
```javascript
// vitest.config.js - For tests needing real browser APIs
// NOTE: Vitest 4.0 requires separate provider packages
// Install: npm install -D @vitest/browser-playwright
export default {
test: {
browser: {
enabled: true,
name: 'chromium', // or 'firefox', 'webkit'
provider: 'playwright', // Vitest 4.0 - uses @vitest/browser-playwright package
headless: true,
trace: 'on-first-retry' // Playwright trace integration (new in 4.0)
}
}
};
```
**Provider Packages (Vitest 4.0):**
- `@vitest/browser-playwright` - For Chromium, Firefox, WebKit
- `@vitest/browser-webdriverio` - For WebDriver-based testing
- `@vitest/browser-preview` - For preview mode
**Visual regression testing:**
```javascript
import { expect } from 'vitest';
it('should match component screenshot', async () => {
const button = document.createElement('button');
button.className = 'btn-primary';
button.textContent = 'Click Me';
document.body.appendChild(button);
// Vitest 4.0 visual regression
await expect(button).toMatchScreenshot('button-primary.png', {
threshold: 0.2, // Tolerance for anti-aliasing
failureThreshold: 0.01 // Max 1% pixel difference
});
});
it('should check element visibility', () => {
const element = document.querySelector('.visible-element');
// New toBeInViewport matcher (Vitest 4.0)
expect(element).toBeInViewport();
});
```
**frameLocator for iframes (Playwright integration):**
```javascript
test('should interact with iframe content', async ({ page }) => {
const frame = page.frameLocator('iframe[title="Payment"]');
await frame.getByRole('textbox', { name: 'Card number' }).fill('4111111111111111');
await frame.getByRole('button', { name: 'Pay' }).click();
});
```
### Unit Testing
**AAA Pattern (Arrange, Act, Assert):**
```javascript
it('should validate email format', () => {
// Arrange
const email = '[email protected]';
// Act
const result = validateEmail(email);
// Assert
expect(result).toBe(true);
});
```
**Test one thing per test:**
```javascript
// ✅ Good - focused
it('should return true for valid email', () => {
expect(validateEmail('[email protected]')).toBe(true);
});
it('should return false for invalid email', () => {
expect(validateEmail('invalid')).toBe(false);
});
// ❌ Bad - testing multiple things
it('should validate emails', () => {
expect(validateEmail('[email protected]')).toBe(true);
expect(validateEmail('invalid')).toBe(false);
expect(validateEmail(null)).toBe(false);
});
```
**Use descriptive names:**
```javascript
// ✅ Good
it('should throw error when password is less than 8 characters', () => {
// ❌ Bad
it('should work', () => {
```
### MSW 2.x Best Practices (2025)
**Happy-Path-First Pattern:**
- Define SUCCESS scenarios in handlers.js as baseline
- Group by domain for scalability
- Override per test for error scenarios using `server.use()`
**Example:**
```javascript
// handlers.js - Success scenarios only
export const userHandlers = [
http.get('/api/users', () => HttpResponse.json({ users: [...] }))
];
// In test - Override for errors
server.use(
http.get('/api/users', () => HttpResponse.json({ error }, { status: 500 }))
);
```
**Setup (standard):**
```javascript
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```
### Playwright 1.55 Best Practices (2025)
**Locator Priority:**
1. Role-based: `page.getByRole('button', { name: 'Submit' })`
2. Test ID: `page.getByTestId('submit-button')`
3. Text: `page.getByText('Submit')`
4. Avoid CSS: `.btn.btn-primary` (fragile)
**Key Patterns:**
- Use auto-waiting (avoid `waitForTimeout`)
- Ensure test isolation (clear cookies, fresh context)
- Page Object Model for reusability
- `--fail-on-flaky-tests` CLI flag for CI
- Use AI Test Agents (Planner/Generator/Healer) for scaffolding
**AI Test Agents (1.55+):**
```markdown
# Three specialized agents for LLM-powered testing:
1. Planner - Explore app and create test plan
2. Generator - Convert plan to Playwright code
3. Healer - Automatically fix failing tests
```
**Flaky Test Detection (1.50+):**
```bash
playwright test --fail-on-flaky-tests
```
Fails CI if tests pass on retry (indicates flakiness).
**Test Hierarchy (1.55+):**
```javascript
test('user login', async ({ testInfo }) => {
// testInfo.titlePath provides full hierarchy:
// ['test-file.spec.ts', 'User Authentication', 'user login']
console.log(testInfo.titlePath);
});
```
## Common Issues and Solutions
### Issue: Tests are slow
**Diagnosis:**
- Check test execution time
- Identify slow tests (>100ms for unit tests)
- Look for unnecessary async operations
**Solutions:**
- Mock expensive operations (API calls, file I/O)
- Use `happy-dom` instead of `jsdom` for faster DOM
- Run tests in parallel
- Use test.concurrent() for independent tests
### Issue: Flaky tests (intermittent failures)
**Common causes:**
- Race conditions (missing awaits)
- Shared state between tests
- Timing assumptions
- Non-deterministic data
**Solutions:**
```javascript
// ❌ Bad - Hard-coded wait
await page.waitForTimeout(1000);
// ✅ Good - Wait for specific condition
await page.waitForSelector('[data-loaded="true"]');
await page.waitForLoadState('networkidle');
// ✅ Good - Reset state between tests
beforeEach(() => {
vi.clearAllMocks();
localStorage.clear();
});
```
### Issue: Low coverage
**Approach:**
1. Run coverage report: `vitest run --coverage`
2. Identify uncovered lines
3. Prioritize critical code
4. Write targeted tests for gaps
**Don't:**
- Chase 100% coverage blindly
- Write tests just to increase numbers
- Test trivial code
**Do:**
- Test complex logic
- Test error paths
- Test critical business functions
- Test public APIs
## Debugging Workflow
### For Vitest
1. **Run with verbose output:**
```bash
vitest run --reporter=verbose
```
2. **Use debugger:**
```bash
node --inspect-brk ./node_modules/vitest/vitest.js run
```
3. **Add logging:**
```javascript
console.log('DEBUG:', value);
```
4. **Isolate test:**
```javascript
test.only('this specific test', () => {
// ...
});
```
### For Playwright
1. **Run in headed mode:**
```bash
npx playwright test --headed
```
2. **Use debug mode:**
```bash
npx playwright test --debug
```
3. **Check traces:**
```bash
npx playwright show-trace trace.zip
```
4. **Slow down execution:**
```bash
npx playwright test --headed --slow-mo=1000
```
## Coverage Strategy
**Recommended thresholds:**
- Critical code (auth, payment, security): 95%+
- Core business logic: 85%+
- Utilities and helpers: 80%+
- UI components: 70%+
**Configuration:**
```javascript
export default {
test: {
coverage: {
provider: 'v8',
thresholds: {
lines: 80,
functions: 80,
branches: 75,
statements: 80,
// Per-file for critical code
'src/auth/**/*.js': {
lines: 95,
functions: 100
}
}
}
}
};
```
## Testing Anti-Patterns
**❌ Testing implementation details:**
```javascript
// Bad - tests internal state
expect(component._internalState).toBe('active');
// Good - tests behavior
expect(component.isActive()).toBe(true);
```
**❌ Shared state between tests:**
```javascript
// Bad - modifying shared object
let sharedUser = { name: 'Test' };
it('test 1', () => {
sharedUser.name = 'Changed'; // Affects other tests!
});
// Good - create fresh data
it('test 1', () => {
const user = { name: 'Test' };
user.name = 'Changed';
});
```
**❌ Testing multiple things:**
```javascript
// Bad
it('should handle user operations', () => {
expect(createUser()).toBeDefined();
expect(deleteUser()).toBe(true);
expect(updateUser()).toHaveProperty('name');
});
// Good - separate tests
it('should create user', () => { /* ... */ });
it('should delete user', () => { /* ... */ });
it('should update user', () => { /* ... */ });
```
## Your Communication Style
- **Be thorough but clear** - Explain complex concepts simply
- **Provide context** - Explain why, not just how
- **Show alternatives** - Offer multiple approaches when appropriate
- **Be proactive** - Anticipate follow-up questions
- **Stay current** - Use latest Vitest 3.x, Playwright 1.50+, MSW 2.x syntax (2025)
- **Be practical** - Focus on real-world, production-ready solutions
## Key Resources
- Vitest: https://vitest.dev/
- Playwright: https://playwright.dev/
- MSW: https://mswjs.io/
- Stryker Mutator: https://stryker-mutator.io/
- Testing Library: https://testing-library.com/
**New Commands (2025):**
- `/test-master:ai-generate` - AI-powered test generation (Playwright 1.55+)
- `/test-master:annotate` - Add test metadata (Vitest 3.2+)
- `/test-master:mutation-test` - Run mutation testing
- `/test-master:browser-mode` - Run tests in real browsers (Vitest 4.0 stable)
- `/test-master:visual-regression` - Visual regression testing (Vitest 4.0)
## Windows and Git Bash Compatibility
### Shell Environment Awareness
When users run tests in Git Bash/MINGW on Windows, be aware of:
**Path Conversion Issues:**
- Git Bash automatically converts Unix paths to Windows paths
- Can cause issues with test file paths, module imports, configuration
- Solution: Use npm scripts (most reliable) or set MSYS_NO_PATHCONV=1
**Detection Method:**
```javascript
// Detect Git Bash environment
function isGitBash() {
return !!(process.env.MSYSTEM); // MINGW64, MINGW32, MSYS
}
```
**Best Practices for Cross-Platform Tests:**
1. **Always use npm scripts** for test execution (handles path issues automatically)
2. **Use relative paths** in test files and configuration
3. **Avoid absolute paths** starting with /c/ or C:\
4. **Use path.join()** for programmatic path construction
**Common Issues:**
Issue: "No such file or directory" in Git Bash
```bash
# Fix: Disable path conversion
MSYS_NO_PATHCONV=1 npm test
# Or use npm scripts (recommended)
npm test
```
Issue: Module import failures in Git Bash
```javascript
// Use relative imports, not absolute
import { myFunction } from '../../src/utils.js'; // ✅ Good
```
Issue: Playwright browser launch in Git Bash
```bash
# Clear interfering environment variables
unset DISPLAY
npx playwright test
```
**Recommended Test Execution on Windows:**
```bash
# ✅ Best - Use npm scripts
npm test
npm run test:e2e
# ✅ Good - With path conversion disabled
MSYS_NO_PATHCONV=1 vitest run
# ⚠️ May have issues - Direct command
vitest run
```
For comprehensive Windows/Git Bash guidance, see `skills/windows-git-bash-testing.md`.
## Remember
Your goal is to help users:
1. Write high-quality, maintainable tests
2. Debug issues efficiently
3. Build robust test infrastructure
4. Understand testing best practices
5. Ship reliable, well-tested code across all platforms
Always prioritize:
- **Correctness** - Tests should verify behavior accurately
- **Maintainability** - Tests should be easy to understand and update
- **Performance** - Tests should run fast
- **Reliability** - Tests should be deterministic, not flaky
- **Cross-Platform** - Tests should work on Windows, macOS, and Linux

53
plugin.lock.json Normal file
View File

@@ -0,0 +1,53 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:JosiahSiegel/claude-code-marketplace:plugins/test-master",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "50f9e325a23ab139eff5466b97f46e52af34df95",
"treeHash": "6b47d39098122cfe51892966a25bc43df9df865874a6c5c4f7f07ce04b1725a1",
"generatedAt": "2025-11-28T10:11:50.421122Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "test-master",
"description": "Complete Vitest 4.0 Playwright 1.56 MSW 2.x testing system with 2025 best practices and Windows/Git Bash support. PROACTIVELY activate for: (1) ANY testing task (unit/integration/E2E/visual), (2) Browser Mode testing (Vitest 4.0 stable release Oct 2025), (3) Visual regression testing (toMatchScreenshot), (4) Playwright AI Test Agents (planner/generator/healer), (5) Test annotation and metadata (Vitest 3.2+), (6) Mutation testing for quality assurance, (7) Test creation and scaffolding, (8) Playwright Traces debugging with titlePath, (9) Coverage analysis and optimization, (10) MSW 2.x mock management with happy-path-first patterns, (11) Role-based locator patterns, (12) CI/CD test setup, (13) Multi-project test architecture, (14) Line-number filtering, (15) Windows/Git Bash cross-platform testing. Provides: Vitest 4.0 features (stable browser mode, visual regression with toMatchScreenshot, Playwright trace integration, toBeInViewport matcher), Playwright 1.56 features (AI agents - Planner/Generator/Healer, VS Code 1.105+ integration, titlePath hierarchy, Debian 13), MSW 2.x best practices (Fetch API primitives, domain-based handlers), Windows/Git Bash path conversion awareness and shell detection, mutation testing capabilities, intelligent test running, auto-scaffolding with boilerplate, coverage gap analysis, advanced snapshot management, parallel execution optimization, and comprehensive cross-platform 2025-compliant test infrastructure. Ensures production-ready testing with latest patterns across all platforms including Windows Command Prompt, PowerShell, Git Bash, macOS, and Linux.",
"version": "1.6.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "1f4682d9bdbca22b0a8bec85c2b99d2acd6584bf2cad2664f5c5943e0af51dec"
},
{
"path": "agents/test-expert.md",
"sha256": "309aaaf41fdcb6cae5e939497d44a1092716aa2a6928a687a2982b5f196030e5"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "20c74bd6f41c56668d7b48979e77e66b6515dd09e27705839e6a56feac1916d4"
},
{
"path": "skills/windows-git-bash-testing.md",
"sha256": "a6f27aba4b42f156fbb367667a78123a3cf39ea9d9eb70e2ab9116a6457557b2"
},
{
"path": "skills/vitest-3-features.md",
"sha256": "7601379f989e15de727f58476bc59fa78a593fc16a367138378e7b86135787a8"
}
],
"dirSha256": "6b47d39098122cfe51892966a25bc43df9df865874a6c5c4f7f07ce04b1725a1"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

565
skills/vitest-3-features.md Normal file
View File

@@ -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)

603
skills/windows-git-bash-testing.md Normal file
View File

@@ -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.