xlwings/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **VBA Automated Testing and Precise Error Reporting System** that enables automated testing of VBA macros in Excel files with exact line-level error reporting using code weaving techniques. The system solves the fundamental problem of debugging VBA macros by providing precise error locations and automated testing capabilities.

## Core Architecture

The system uses a **code weaving pattern** to instrument VBA code at runtime:

1. **CodeWeaver Class** (`vba_test_runner.py`): Parses VBA code, injects line number labels (10, 20, 30...) before executable code, and adds error handling with `On Error GoTo` statements. Generates source maps mapping line numbers to original source code.

2. **LoggerInjector Class**: Manages test logging infrastructure by injecting a `TestLogger` module and `CallStack` class into the VBA project for tracking execution flow and capturing results.

3. **TestRunner Class**: Coordinates the testing process - manages Excel application lifecycle, handles VBA code hot-swapping, executes macros, and ensures files remain unmodified (non-invasive).

4. **TestResult Data Class**: Structured container for procedure results including error details, source code mapping, error location, and call chain information.

### How Code Weaving Works

The system:
- Parses VBA code to identify all Sub/Function procedures
- Injects numeric line labels (10, 20, 30...) before executable code (skipping declarations, comments, empty lines)
- Adds `On Error GoTo` error handlers at procedure start
- Uses VBA's `Erl()` function to capture the last executed line number
- Maps line numbers back to original source code via Source Map
- Hot-swaps module code in Excel memory (never saves to disk)

### Error Detection Mechanism

- Leverages VBA's `Erl()` function which returns the last executed line number label
- Maintains a source map from injected line numbers to original source code
- Tracks call chains through LogEntry/LogExit in the TestLogger
- Displays exact error location with original source code context

## Development Commands

### Virtual Environment Requirement

**IMPORTANT**: Always activate the virtual environment before running any test scripts. The project uses a virtual environment located at `.venv`:

```bash
# On Windows
.venv\Scripts\activate

# On Linux/Mac
source .venv/bin/activate
```

Never run `vba_test_runner.py` or other Python scripts directly from the system Python environment. Always ensure the virtual environment is active first.

### Install Dependencies
```bash
pip install xlwings pywin32
```

### Running Tests

Test a single procedure:
```bash
python vba_test_runner.py demo.xlsm Module1 TestErrorProcedure
```

Test multiple procedures:
```bash
python vba_test_runner.py demo.xlsm Module1 TestErrorProcedure TestTypeMismatch TestSubscriptError
```

Full project testing (discovers and tests all procedures):
```bash
python vba_test_runner.py demo.xlsm --all
```

### Excel Configuration Requirement

Before running tests, enable "Trust access to the VBA project object model" in Excel:
- Open Excel > File > Options > Trust Center > Trust Center Settings
- Go to Macro Settings
- Check: "Trust access to the VBA project object model"
- Restart Excel

## Key Implementation Details

### Line Number Label Rules
- Use pure numbers without colons: `10`, `20`, `30`...
- Only inject before executable code
- Skip declaration blocks (Dim, Private, etc.)
- Skip comments and empty lines
- Skip existing On Error statements

### Hot-Swap Non-Invasive Testing
All code modifications happen in memory. The system:
1. Reads original VBA code from Excel file
2. Applies code weaving transformations
3. Replaces module code in Excel's VBProject
4. Executes tests
5. Closes workbook with `SaveChanges=False`

Original Excel files are never modified.

### Procedure Filtering
- Automatically excludes Worksheet_ and Workbook_ event procedures
- Only processes standard modules and class modules (Type 1 and 2)
- Supports both single procedure and full project testing modes

### TestResult Structure
```python
@dataclass
class TestResult:
    procedure_name: str
    success: bool
    error_number: int = 0
    error_description: str = ""
    error_line: int = 0
    source_code: str = ""
    error_module: str = ""      # Module where error occurred
    call_chain: str = ""         # Full call stack
```

## Main Entry Point

```python
if __name__ == "__main__":
    main()  # Handles both single procedure and full project testing
```

Core methods:
- `TestRunner.run_test()`: Execute a single test procedure
- `TestRunner.run_all_tests()`: Discover and execute all testable procedures
- `CodeWeaver.weave_procedure()`: Weave a single procedure
- `CodeWeaver.weave_all_modules()`: Weave all modules in a project
- `CodeWeaver.parse_modules()`: Parse all modules in a VBA project

## Limitations

- Only supports standard modules and class modules (not form modules)
- Line number label conflicts possible if original code uses same numeric labels
- Complex procedures with many GoTo statements may require additional handling
- Requires Excel VBA project object model access (security setting)