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

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

## 🧪 **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*