testdrive-jsui/README.md

TestDrive-JSUI

A standalone JavaScript UI rendering engine and testing framework. Originally developed for MarkiTect, TestDrive-JSUI is designed as an independent, reusable capability that can be integrated into any Python project.

🎯 Purpose

TestDrive-JSUI is designed to:

• 📝 Render markdown with interactive JavaScript UI for editing and viewing
• 🔌 Work as a standalone plugin or integrate with any Python project
• 🔒 Protect existing JavaScript UI functionality during refactoring and development
• 🧪 Integrate JavaScript tests into Python test suites
• 🏗️ Provide a clean architecture for JavaScript framework development
• 📊 Enable comprehensive testing of JavaScript UI components
• 🚀 Support extensibility for JavaScript framework evolution

🏗️ Architecture

capabilities/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 (consolidated)
│   ├── core/                    # Core JS (debug-system, section-manager)
│   ├── components/              # UI components (dom-renderer, debug-panel)
│   ├── controls/                # Control panels (edit, debug, status, contents)
│   ├── plugins/                 # JS plugins
│   ├── widgets/                 # UI widgets
│   ├── utils/                   # JS utilities
│   ├── tests/                   # JavaScript tests
│   ├── config-loader.js         # Configuration loader
│   ├── main.js                  # Main entry point
│   └── main-updated.js          # Updated main (refactored)
├── static/                      # Static assets
│   ├── css/                     # Stylesheets
│   │   ├── editor.css           # Editor styles
│   │   ├── controls.css         # Control panel styles
│   │   └── themes/              # Theme files
│   ├── images/                  # Image assets
│   │   └── icons/               # UI icons
│   └── templates/               # HTML templates
│       └── index.html           # Main template
├── tests/                       # Python tests
├── Makefile                     # Capability commands
├── pyproject.toml              # Python package config
├── package.json                # JavaScript dependencies
└── README.md                   # This file

Key Design Principles:

• Single Source of Truth: All assets in one capability directory
• Self-Declaration: Plugin declares its own paths (no hardcoded discovery)
• Clean Boundaries: JSON config interface between Python and JavaScript
• No Code Mixing: JavaScript stays in .js files, never embedded in Python
• Plugin Independence: Can be moved/installed anywhere

🚀 Quick Start

Prerequisites

• Python 3.8+ with pip
• Node.js 16+ with npm (optional, for JavaScript testing)

Standalone Installation

TestDrive-JSUI can be used completely independently of MarkiTect:

# Clone or copy this directory
git clone <repo-url> testdrive-jsui
cd testdrive-jsui

# Install Python package in development mode
pip install -e .

# (Optional) Install JavaScript dependencies for testing
npm install

Integration with MarkiTect

If using within the MarkiTect project:

# 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

📦 Standalone Usage

As a Rendering Engine Plugin

TestDrive-JSUI implements a plugin interface that allows it to be used independently:

from pathlib import Path
from testdrive_jsui import TestDriveJSUIEngine

# Create engine instance
engine = TestDriveJSUIEngine()

# The engine declares its own location - no hardcoded paths!
source_dir = engine.get_plugin_source_dir()
print(f"Plugin located at: {source_dir}")

# Get organized asset paths
asset_paths = engine.get_asset_paths()
# Returns: {'js': Path(...), 'css': Path(...), 'images': Path(...), 'templates': Path(...)}

# Get required assets list
assets = engine.get_required_assets()
# Returns: {'js': [...], 'css': [...], 'images': [...], 'external': [...]}

Rendering Documents

Use the engine to render markdown content with an interactive JavaScript UI:

from testdrive_jsui import TestDriveJSUIEngine
from markitect.plugins.rendering import RenderingConfig
from pathlib import Path

# Create engine
engine = TestDriveJSUIEngine()

# Configure for development (serves from source)
config = RenderingConfig(
    asset_base_url='.',
    development_mode=True,
    plugin_source_dirs={'testdrive-jsui': engine.get_plugin_source_dir()}
)

# Render markdown content
markdown_content = """
# My Document

This is a test of the **TestDrive-JSUI** rendering engine.

## Features
- Interactive editing
- Section management
- Debug controls
"""

html = engine.render_document(markdown_content, 'edit', config)

# Save to file
Path('output.html').write_text(html)
print("✅ Rendered to output.html")

Production Deployment

For production, deploy assets to a static directory:

from testdrive_jsui import TestDriveJSUIEngine
from markitect.plugins.rendering import RenderingConfig
from pathlib import Path

engine = TestDriveJSUIEngine()

# Configure for production
config = RenderingConfig(
    asset_base_url='/_static',
    development_mode=False,
    output_directory=Path('./dist')
)

# Assets will be copied to: dist/_static/plugins/testdrive-jsui/
html = engine.render_document(content, 'view', config)

Plugin Independence

TestDrive-JSUI is designed to be fully independent:

• ✅ Self-contained: All assets in one directory
• ✅ Self-declaring: Plugin declares its own location
• ✅ No hardcoded paths: Works regardless of installation location
• ✅ Clean interface: Pure JSON configuration boundary
• ✅ No JavaScript in Python: All JS in separate files
• ✅ Reusable: Can be used in any Python project

Supported Modes

# Check supported rendering modes
modes = engine.get_supported_modes()
# Returns: ['edit', 'view']

# Validate a mode
if engine.validate_mode('edit'):
    html = engine.render_document(content, 'edit', config)

🧪 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