markitect-main/capabilities/testdrive-jsui/README.md

TestDrive-JSUI Capability

A comprehensive JavaScript UI testing framework capability for MarkiTect. Provides seamless integration between Python and JavaScript testing environments, enabling safe development and testing of JavaScript UI components.

🎯 Purpose

TestDrive-JSUI is designed to:

• 🔒 Protect existing JavaScript UI functionality during refactoring and development
• 🧪 Integrate JavaScript tests into the main Python test suite
• 🏗️ Provide a clean architecture for JavaScript framework development
• 📊 Enable comprehensive testing of JavaScript UI components
• 🚀 Support future extensibility for JavaScript framework evolution

🏗️ Architecture

testdrive-jsui/
├── src/testdrive_jsui/          # Python package
│   ├── core/                    # Core framework components
│   ├── components/              # UI component helpers
│   ├── utils/                   # Utility functions
│   └── testing/                 # Python-JS bridge
│       ├── js_test_runner.py    # JavaScript test execution
│       └── integration.py       # Pytest integration
├── js/                          # JavaScript source
│   ├── core/                    # Core JS components
│   ├── components/              # UI components
│   ├── utils/                   # JS utilities
│   └── tests/                   # JavaScript tests
├── tests/                       # Python tests
├── Makefile                     # Capability commands
├── pyproject.toml              # Python package config
├── package.json                # JavaScript dependencies
└── README.md                   # This file

🚀 Quick Start

Prerequisites

• Python 3.8+ with pip
• Node.js 16+ with npm
• MarkiTect main project installed

Installation

# Navigate to the capability directory
cd capabilities/testdrive-jsui

# Quick setup (installs everything)
make testdrive-jsui-quickstart

# Or step by step:
make testdrive-jsui-setup           # Install all dependencies
make testdrive-jsui-status          # Check environment
make testdrive-jsui-test-all        # Run all tests

🧪 Testing

JavaScript Tests

# Run JavaScript tests only
make testdrive-jsui-test-js

# Run with coverage
npm run test:coverage

# Watch mode for development
make testdrive-jsui-watch

Python Integration Tests

# Run Python tests only
make testdrive-jsui-test-python

# Run integration tests
make testdrive-jsui-test-integration

# Run all tests
make testdrive-jsui-test-all

Main Project Integration

From the main MarkiTect project:

# Run capability tests
make testdrive-jsui-test-all

# Include in main test suite
make test-all  # (when integrated)

📋 Available Commands

Command	Description
make testdrive-jsui-help	Show all available commands
make testdrive-jsui-status	Check environment status
make testdrive-jsui-setup	Install all dependencies
make testdrive-jsui-test-all	Run all tests
make testdrive-jsui-watch	Development watch mode
make testdrive-jsui-clean	Clean build artifacts

🔧 Development

Adding JavaScript Tests

1. Create test files in js/tests/:

   // js/tests/test-my-component.js
   describe('MyComponent', () => {
     test('should do something', () => {
       // Your test here
     });
   });
   

2. Run tests:

   make testdrive-jsui-test-js
   

Adding Python Integration Tests

1. Create test files in tests/:

   # tests/test_my_integration.py
   import pytest
   from testdrive_jsui.testing import JavaScriptTestRunner
   
   @pytest.mark.javascript
   def test_my_js_component():
       runner = JavaScriptTestRunner()
       result = runner.run_specific_test('test-my-component.js')
       assert result.success
   

2. Run tests:

   make testdrive-jsui-test-integration
   

Code Quality

# Lint JavaScript
make testdrive-jsui-lint-js

# Lint Python
make testdrive-jsui-lint-python

# Format Python code
make testdrive-jsui-format-python

🔗 Integration with Main Project

Python Test Suite Integration

The capability provides pytest integration to run JavaScript tests from Python:

# In main project tests
from testdrive_jsui.testing import JavaScriptTestRunner

def test_javascript_ui_components():
    runner = JavaScriptTestRunner()
    result = runner.run_js_tests()
    assert result.success
    assert result.tests_passed > 0

Capability System Integration

The capability integrates with MarkiTect's capability discovery system:

# From main project
make capabilities-list                    # Shows testdrive-jsui
make testdrive-jsui-test-all             # Direct delegation
make capabilities-test                    # Includes JS tests

📊 Testing Framework Features

JavaScript Test Runner

• Jest integration with JSDOM environment
• Coverage reporting with detailed metrics
• Test isolation with proper setup/teardown
• Mock support for DOM APIs and browser features
• Async testing support for modern JavaScript

Python-JavaScript Bridge

• Subprocess execution of JavaScript tests
• Result parsing with structured output
• Error handling with detailed failure information
• Test discovery for pytest integration
• Coverage integration between Python and JavaScript

Safety Mechanisms

• Copy-first migration (never move, always copy)
• Dual-track testing during migration
• Gradual integration with rollback options
• Test verification at each step
• Environment validation before execution

🔄 Migration Strategy

When migrating JavaScript UI code to this capability:

1. Copy (don't move) JavaScript files to js/ directory
2. Verify tests work in new location
3. Create Python integration tests
4. Run dual-track testing to compare results
5. Gradually switch to capability-based testing
6. Remove original files only after full verification

📚 Examples

Running Specific Tests

# Run a specific JavaScript test
npm test -- --testNamePattern="SectionManager"

# Run specific Python integration test
pytest tests/test_section_manager_integration.py -v

# Run tests with coverage
npm run test:coverage

Environment Information

# Get detailed environment info
make testdrive-jsui-info

# Check what tests are available
make testdrive-jsui-status

Development Workflow

# Start development session
make testdrive-jsui-watch         # Terminal 1: Watch JS tests
make testdrive-jsui-test-python   # Terminal 2: Run Python tests

# Before committing
make testdrive-jsui-lint-js       # Lint JavaScript
make testdrive-jsui-format-python # Format Python
make testdrive-jsui-test-all      # Run all tests

🎯 Future Enhancements

• Visual regression testing with screenshot comparison
• Performance benchmarking for JavaScript components
• Browser automation with Selenium/Playwright
• Component documentation auto-generation
• Real browser testing in CI/CD pipelines

📋 Troubleshooting

Common Issues

Node.js not found:

# Install Node.js first
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Tests failing:

# Check environment
make testdrive-jsui-status

# Reinstall dependencies
make testdrive-jsui-clean
make testdrive-jsui-setup

Integration issues:

# Verify Python package is installed
pip list | grep testdrive-jsui

# Check JavaScript dependencies
npm list

📄 License

MIT License - See main MarkiTect project for details.

---

Generated: 2025-11-09 Status: Phase 1 Implementation Next: Copy JavaScript files and create integration tests