markitect-main/docs/workplan-testdrive-jsui-capability.md

TestDrive-JSUI Capability Implementation Workplan

🎯 Objective

Safely extract JavaScript UI framework functionality into a dedicated testdrive-jsui capability while:

• Protecting existing hard-won JavaScript UI functionality
• Integrating JavaScript tests into the main Python test suite
• Maintaining 100% test coverage and functionality
• Creating a clean, extensible architecture for future JavaScript framework development

🔍 Current State Analysis

JavaScript UI Infrastructure:

markitect/static/js/
├── core/
│   └── section-manager.js         (17K lines - Core component)
├── components/
│   ├── debug-panel.js            (5.8K lines)
│   ├── document-controls.js      (7.9K lines)
│   └── dom-renderer.js           (40K lines - Major component)
├── utils/                         (Empty - utilities)
└── tests/                        (2.8K total lines)
    ├── refactor-test-runner.js    (Custom test framework)
    ├── test-*.js                  (11 comprehensive test files)
    └── [Component-specific tests]

Testing Infrastructure:

• ✅ Jest framework configured (package.json)
• ✅ JSDOM environment for DOM testing
• ✅ Custom RefactorTestRunner for TDD workflow
• ✅ 11 comprehensive test files (2,840 lines total)
• ✅ Component integration tests
• ✅ Full workflow testing

Feasibility: HIGHLY FEASIBLE ✅

• Well-structured components with clear separation
• Comprehensive test coverage
• Modern tooling (Jest + JSDOM)
• Modular design already in place
• TDD approach designed for safe refactoring

🚀 Implementation Phases

Phase 1: Foundation Setup ⏱️ ~2-4 hours

Step 1.1: Create testdrive-jsui Capability Structure

capabilities/testdrive-jsui/
├── src/testdrive_jsui/
│   ├── __init__.py
│   ├── core/                    # Framework components
│   ├── components/              # UI components
│   ├── utils/                   # Utilities
│   └── tests/                   # Python test wrappers
├── tests/                       # Native Python tests
├── js/                          # JavaScript source
│   ├── core/
│   ├── components/
│   ├── utils/
│   └── tests/
├── Makefile                     # Capability Makefile
├── pyproject.toml              # Package config
├── package.json                # JS dependencies
├── jest.config.js              # Jest configuration
└── README.md                   # Documentation

Step 1.2: Setup Package Configuration

• pyproject.toml: Python package with subprocess/node dependencies
• package.json: Jest + JSDOM + custom dependencies
• Makefile: Integration with main capability system
• jest.config.js: Proper test environment setup

Step 1.3: Create Python-JavaScript Bridge

# testdrive_jsui/testing/js_test_runner.py
class JavaScriptTestRunner:
    def run_js_tests(self, test_patterns=None):
        """Run JavaScript tests via Node.js and return results"""

    def integrate_with_pytest(self):
        """Make JS tests discoverable by pytest"""

Phase 2: Integration Layer ⏱️ ~3-5 hours

Step 2.1: Python Test Wrappers

# Integration approach: Subprocess-based
def test_section_manager_component():
    result = js_test_runner.run_test('test-section-manager-extraction.js')
    assert result.success
    assert result.tests_passed > 0

def test_dom_renderer_component():
    result = js_test_runner.run_test('test-domrenderer-extraction.js')
    assert result.success

Step 2.2: Main Test Suite Integration

• Add JS test discovery to pytest
• Create test markers for JavaScript tests
• Setup parallel execution (optional)
• Integrate with main Makefile test targets

Step 2.3: Capability Makefile Targets

# capabilities/testdrive-jsui/Makefile
.PHONY: testdrive-jsui-test-js
testdrive-jsui-test-js: ## Run JavaScript tests
	npm test

.PHONY: testdrive-jsui-test-integration
testdrive-jsui-test-integration: ## Run Python-JS integration tests
	pytest tests/

.PHONY: testdrive-jsui-test-all
testdrive-jsui-test-all: ## Run all tests (JS + Python integration)
	npm test && pytest tests/

Phase 3: Safe Migration ⏱️ ~4-6 hours

Step 3.1: Copy & Test Strategy

# 1. Copy (don't move) JavaScript files to capability
cp -r markitect/static/js/* capabilities/testdrive-jsui/js/

# 2. Verify tests still work in new location
cd capabilities/testdrive-jsui && npm test

# 3. Create Python wrappers and verify integration
pytest capabilities/testdrive-jsui/tests/

# 4. Add to main test suite gradually
make test  # Ensure main suite still passes

Step 3.2: Dual-Track Testing (Safety First!)

• Keep original files until migration complete
• Run both locations in parallel initially
• Compare test results for consistency
• Gradual cutover with rollback option

Phase 4: Framework Enhancement ⏱️ ~2-3 hours

Step 4.1: Enhanced Testing Framework

// Enhanced RefactorTestRunner with Python integration
class EnhancedTestRunner extends RefactorTestRunner {
    reportToPython(results) {
        // JSON output for Python consumption
    }

    runWithCoverage() {
        // Coverage reporting
    }
}

Step 4.2: Advanced Features

• Coverage reporting (Istanbul/nyc)
• Performance benchmarks
• Visual regression testing (optional)
• Component documentation auto-generation

Phase 5: Production Integration ⏱️ ~1-2 hours

Step 5.1: Main Test Suite Enhancement

# Add to main Makefile
.PHONY: test-js
test-js: ## Run JavaScript UI tests
	make testdrive-jsui-test-all

.PHONY: test-all
test-all: test test-js test-capabilities ## Run all tests including JS

Step 5.2: CI/CD Integration

• Update test commands in main suite
• Ensure capability auto-discovery works
• Add JS test markers for selective running

🔒 Safety Mechanisms

Risk Mitigation:

1. 📁 Copy-First Approach: Never move, always copy initially
2. 🔄 Dual Testing: Run tests in both locations during migration
3. ✅ Gradual Integration: Add to main suite incrementally
4. 🎯 Rollback Plan: Keep original structure until 100% verified
5. 🧪 Test Verification: Compare results before/after migration

Success Criteria:

• ✅ All existing JS tests pass in new capability
• ✅ Python integration tests pass
• ✅ Main test suite still 100% green
• ✅ JavaScript UI functionality unchanged
• ✅ Performance maintained or improved

📋 Implementation Checklist

Phase 1: Foundation

• Create capability directory structure
• Setup pyproject.toml with dependencies
• Create package.json with Jest configuration
• Implement Python-JavaScript bridge
• Create capability Makefile
• Write basic README documentation

Phase 2: Integration

• Create Python test wrappers for JS tests
• Integrate with pytest discovery
• Add capability targets to main Makefile
• Test integration with main test suite

Phase 3: Migration

• Copy JavaScript files to capability
• Verify tests work in new location
• Create dual-track testing setup
• Gradually integrate with main suite

Phase 4: Enhancement

• Enhance test framework with Python integration
• Add coverage reporting
• Performance benchmarking
• Documentation generation

Phase 5: Production

• Full integration with main test suite
• CI/CD pipeline updates
• Final verification and cleanup

⚡ Quick Start Option

For immediate JavaScript test integration (30 minutes):

def test_javascript_ui_components():
    """Run all JavaScript tests via subprocess"""
    import subprocess
    result = subprocess.run(['npm', 'test'],
                          capture_output=True, text=True)
    assert result.returncode == 0, f"JS tests failed: {result.stderr}"

🎯 Expected Outcomes

• 🔒 Zero-risk migration with copy-first approach
• 🧪 Enhanced testing with Python integration
• 📊 Better CI/CD integration
• 🏗️ Clean architecture with capability isolation
• 🚀 Future extensibility for JavaScript framework evolution

⏱️ Timeline

Total Estimated Time: 12-20 hours (can be done incrementally)

Recommended approach: Start with Phase 1 for immediate value and safe migration path setup.

---

Generated: 2025-11-09 Status: Ready for Implementation