test-guided-migration-assistant

Test-Guided Migration Assistant

Automatically update a codebase to a new language version, framework version, or library update while ensuring all tests continue to pass.

Workflow

1. Establish Baseline

Before starting migration, establish the current state:

# Run full test suite
<test_command>

# Record baseline
# - Total tests: X
# - Passing: Y
# - Failing: Z (should be 0 or known failures)
# - Coverage: N%

Document current state:

• Current versions (language, framework, dependencies)
• Test results
• Any known issues

2. Understand Migration Context

Gather information:

• Target version (e.g., Python 3.12, React 18, Django 4.2)
• Migration scope (single library vs. full stack)
• Breaking changes expected

Consult migration guides:

• Official migration documentation
• Changelog/release notes
• Community migration guides
• See migration_scenarios.md for common patterns

Identify risks:

• Deprecated API usage
• Known breaking changes
• Custom integrations affected
• Performance implications

3. Perform Migration

Update dependencies:

Incremental approach (recommended):

# Update one dependency at a time
npm install package@new-version
# or
pip install package==new-version

# Run tests immediately
<test_command>

Batch approach (for experienced migrations):

# Update all dependencies
npm update
# or
pip install -U -r requirements.txt

# Run tests
<test_command>

Update configuration:

• Update build configuration
• Update CI/CD configuration
• Update environment files
• Update Docker images

4. Analyze Test Failures

Run tests and capture output:

# Pytest
pytest -v > test_output.txt 2>&1

# Jest
npm test > test_output.txt 2>&1

# Other frameworks
<test_command> > test_output.txt 2>&1

Use analysis script:

python scripts/analyze_test_failures.py test_output.txt

The script categorizes failures into:

• 🔴 Import/Module Errors (CRITICAL - fix first)
• 🟠 API Signature Errors (HIGH priority)
• 🟡 Type Errors (MEDIUM priority)
• 🟡 Configuration Errors (MEDIUM priority)
• 🟢 Behavior Changes (review carefully)
• 🔵 Deprecation Warnings (fix when possible)