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:

# 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

pip install xlwings pywin32

Running Tests

Test a single procedure:

python vba_test_runner.py demo.xlsm Module1 TestErrorProcedure

Test multiple procedures:

python vba_test_runner.py demo.xlsm Module1 TestErrorProcedure TestTypeMismatch TestSubscriptError

Full project testing (discovers and tests all procedures):

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

@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

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)