Windows Testing Guide

This guide describes the Windows-specific tests for the PRISM validator and how to run them.

Overview

Since PRISM was originally developed on macOS, comprehensive Windows testing is essential to ensure cross-platform compatibility. The Windows test suite covers:

  • Path handling (backslashes, drive letters, UNC paths)

  • Filename validation (reserved names, invalid characters)

  • System file filtering (Thumbs.db, Desktop.ini, etc.)

  • File I/O operations (line endings, encodings, Unicode)

  • Web upload functionality

  • Dataset validation on Windows filesystems

Test Files

1. test_windows_compatibility.py

Core Windows Compatibility Tests

Tests basic cross-platform utilities:

  • Platform detection

  • Path normalization

  • Filename validation

  • Case sensitivity detection

  • JSON handling with various encodings

Run:

python tests/test_windows_compatibility.py

2. test_windows_paths.py

Windows Path & Filename Handling

Comprehensive tests for Windows-specific path scenarios:

  • Drive letters (C:, D:, etc.)

  • UNC network paths (\server\share)

  • Long paths (>260 characters)

  • Mixed path separators (/, )

  • Relative paths with backslashes

  • Reserved filenames (CON, PRN, AUX, etc.)

  • Invalid characters (<, >, :, “, |, ?, *)

  • Trailing spaces and dots

  • Filename length limits

Run:

python tests/test_windows_paths.py

3. test_windows_web_uploads.py

Windows Web Interface Upload Tests

Tests web upload functionality with Windows considerations:

  • Upload path normalization

  • Drive letter handling in paths

  • Large batch uploads (5000+ files)

  • DataLad-style uploads (metadata only)

  • Session directory management

  • Temporary file cleanup

  • Concurrent session isolation

  • Path traversal prevention

  • Filename injection prevention

Run:

python tests/test_windows_web_uploads.py

4. test_windows_datasets.py

Windows Dataset Validation Tests

Tests PRISM dataset validation on Windows:

  • Case-insensitive filesystem behavior

  • Mixed case subject folders

  • Windows path validation

  • System file filtering in datasets

  • Locked file handling

  • Long filename paths

  • Read-only file handling

  • .bidsignore with Windows paths

  • Cross-platform dataset compatibility

Run:

python tests/test_windows_datasets.py

Running All Tests

Quick Run

python tests/run_windows_tests.py

This will run all four test suites sequentially and provide a summary.

Individual Test Runs

# Core compatibility
python tests/test_windows_compatibility.py

# Path handling
python tests/test_windows_paths.py

# Web uploads
python tests/test_windows_web_uploads.py

# Dataset validation
python tests/test_windows_datasets.py

Within Virtual Environment

# Activate virtual environment first
.\.venv\Scripts\Activate.ps1

# Then run tests
python tests/run_windows_tests.py

Test Output

Each test provides detailed output:

  • ✅ Test passed

  • ❌ Test failed

  • ⚠️ Warning (non-critical issue or platform-specific note)

  • ℹ️ Information

Example output:

🧪 Testing drive letters...
  ✅ C:\Users\test\dataset -> C:/Users/test/dataset
  ✅ D:\data\prism -> D:/data/prism
  
🧪 Testing reserved filenames...
  ✅ Detected: CON.json - Filename 'CON.json' uses Windows reserved name
  ✅ Detected: PRN.tsv - Filename 'PRN.tsv' uses Windows reserved name

Windows-Specific Considerations

Case Sensitivity

Windows filesystems (NTFS, FAT32) are case-insensitive but case-preserving:

  • Sub-01 and sub-01 refer to the same directory

  • PRISM normalizes to lowercase for consistency

  • Tests verify proper handling

Path Separators

Windows uses backslashes (\) but Python/PRISM normalizes to forward slashes (/):

  • Input: C:\Users\test\dataset

  • Normalized: C:/Users/test/dataset

Reserved Names

Windows reserves certain names that cannot be used as filenames:

  • Device names: CON, PRN, AUX, NUL

  • Serial ports: COM1-COM9

  • Parallel ports: LPT1-LPT9

Tests verify these are properly detected and rejected.

Invalid Characters

Windows does not allow these characters in filenames:

  • < > : " | ? *

  • Trailing spaces or dots

Tests verify proper validation.

Long Paths

Traditional Windows has a 260-character path limit. Modern Windows 10+ can support longer paths if enabled:

# Enable long paths (requires admin)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Tests verify behavior with and without long path support.

System Files

Windows-specific system files that should be ignored:

  • Thumbs.db - Thumbnail cache

  • ehthumbs.db - Enhanced thumbnails

  • Desktop.ini - Folder settings

  • $RECYCLE.BIN - Recycle bin

  • System Volume Information - System restore

Line Endings

Windows uses CRLF (\r\n), while Unix uses LF (\n). PRISM normalizes line endings for cross-platform compatibility.

Common Issues

Test Failures on Non-Windows Platforms

If running these tests on macOS/Linux:

⚠️ Warning: Not running on Windows!
Some tests may behave differently on non-Windows platforms.

This is expected. Some tests will pass with warnings, others may fail due to platform differences (e.g., case sensitivity, reserved names).

Permission Errors

If tests fail with permission errors:

# Run PowerShell as Administrator
# Or check antivirus software isn't blocking file operations

Import Errors

If you see import errors:

# Ensure you're in the correct directory
cd c:\Users\karl\github\prism-validator

# Activate virtual environment
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

Long Path Issues

If tests fail due to path length:

# Check if long paths are enabled
Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled"

# Enable if needed (requires admin)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Continuous Integration

For CI/CD pipelines on Windows:

# GitHub Actions example
- name: Run Windows Tests
  if: runner.os == 'Windows'
  run: |
    python tests/run_windows_tests.py

Contributing

When adding new Windows-specific tests:

  1. Add tests to the appropriate file or create a new one

  2. Follow existing test structure (test classes with test_* methods)

  3. Include descriptive print statements for test progress

  4. Handle non-Windows platforms gracefully (warnings, not failures)

  5. Update this documentation

Support

For Windows-specific issues:

  1. Check the test output for specific error messages

  2. Review WINDOWS_SETUP.md for configuration

  3. Check GitHub Issues for similar problems

  4. Create a new issue with:

    • Windows version

    • Python version

    • Full test output

    • Error messages