# 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:

```bash
# 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:

```bash
# 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:

```python
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:

```python
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:

```python
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

```python
# 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

```bash
# 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

```bash
# 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:

```bash
# 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/`:
   ```javascript
   // js/tests/test-my-component.js
   describe('MyComponent', () => {
     test('should do something', () => {
       // Your test here
     });
   });
   ```

2. Run tests:
   ```bash
   make testdrive-jsui-test-js
   ```

### Adding Python Integration Tests

1. Create test files in `tests/`:
   ```python
   # 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:
   ```bash
   make testdrive-jsui-test-integration
   ```

### Code Quality

```bash
# 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:

```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:

```bash
# 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

```bash
# 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

```bash
# Get detailed environment info
make testdrive-jsui-info

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

### Development Workflow

```bash
# 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:**
```bash
# Install Node.js first
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```

**Tests failing:**
```bash
# Check environment
make testdrive-jsui-status

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

**Integration issues:**
```bash
# 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*