mirror of https://github.com/sbroenne/mcp-server-excel.git synced 2026-09-19 07:53:08 +08:00

Files

T

Stefan Broenner 073f25450b refactor: simplify telemetry - always enabled, build-time connection string (#246 )

* refactor: simplify telemetry - always enabled, build-time connection string

- Remove opt-out functionality (EXCELMCP_TELEMETRY_OPTOUT)
- Embed AppInsights connection string at build time via MSBuild
- Add Directory.Build.props.user for local dev connection string
- Remove runtime environment variable lookup for connection string
- Update release workflows to pass connection string to build
- Remove obsolete test.runsettings file
- Simplify IsEnabled to always return true

* refactor: consolidate prompts and improve tool descriptions

- Reduce prompts from 14 to 2 (keep only high-value guides)
- Remove 13 orphaned .md content files
- Fix ExcelWorksheetTool incorrect 'save' action reference
- Improve ExcelRangeTool and ExcelNamedRangeTool descriptions
- Slim ServerInstructions to essential info only
- Remove redundant telemetry flush (SDK handles automatically)

* refactor(telemetry): disable dependency tracking for HTTP calls in telemetry configuration

* test hook

* fix: correct Application Insights telemetry context

- Set Component.Version explicitly to override SDK auto-detection
  (was picking up Excel COM interop 15.0.0.0 instead of app 1.0.0)
- Anonymize cloud_RoleInstance (was exposing machine name)
- Now all telemetry context values are privacy-safe:
  - application_Version: from assembly metadata
  - cloud_RoleName: fixed 'ExcelMcp.McpServer'
  - cloud_RoleInstance: anonymous hash 'instance-xxxx'
  - user_Id: anonymous hash of machine identity
  - session_Id: random per session

* fix: telemetry improvements for Users/Sessions analytics

- Remove debug mode from telemetry (simplify code)
- Fix PageView tracking to include duration (required for User Flows)
- Always override application_Version (SDK picks up Excel 15.0.0.0)
- Add explicit Flush() call in smoke tests for reliable telemetry delivery
- Fix smoke test shutdown to use graceful shutdown before cancellation

Telemetry now correctly populates:
- requests table (with duration, success, resultCode)
- pageViews table (with duration for User Flows)
- user_Id and session_Id (for Users/Sessions blades)
- application_Version (MCP Server version, not Excel)

2025-12-01 13:34:39 +00:00

ExcelMcp.CLI.Tests

Fix Rule 1b violation in PowerQuery List() (#238 )

2025-11-24 19:47:12 +00:00

ExcelMcp.ComInterop.Tests

fix: replace empty catch blocks with specific exception types (#244 )

2025-11-26 08:29:49 +00:00

ExcelMcp.Core.Tests

Fix Rule 1b violation in PowerQuery List() (#238 )

2025-11-24 19:47:12 +00:00

ExcelMcp.McpServer.Tests

refactor: simplify telemetry - always enabled, build-time connection string (#246 )

2025-12-01 13:34:39 +00:00

Directory.Build.props

refactor: simplify telemetry - always enabled, build-time connection string (#246 )

2025-12-01 13:34:39 +00:00

README.md

fix: CodeQL useless-assignment violation in ExcelRangeTool.SetStyleAsync + scripts cleanup (#120 )

2025-11-04 06:33:59 +00:00

README.md

ExcelMcp Tests

⚠️ No Traditional Unit Tests: ExcelMcp has no unit tests. Integration tests ARE our unit tests because Excel COM cannot be meaningfully mocked. See docs/ADR-001-NO-UNIT-TESTS.md for full architectural rationale.

Quick Start

# Development (fast feedback - excludes VBA tests)
dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA&Feature!=VBATrust"

# Pre-commit (comprehensive - excludes VBA tests)
dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA&Feature!=VBATrust"

# Session/batch changes (MANDATORY when modifying session/batch code)
dotnet test --filter "RunType=OnDemand"

# VBA tests (manual only - requires VBA trust enabled)
dotnet test --filter "(Feature=VBA|Feature=VBATrust)&RunType!=OnDemand"

Documentation

For complete testing guidance, see:

Testing Strategy - Quick reference, templates, common mistakes
Critical Rules - Mandatory development rules (Rule 14: SaveAsync)

Test Architecture

tests/
├── ExcelMcp.Core.Tests/      # Core business logic (Unit + Integration)
├── ExcelMcp.McpServer.Tests/ # MCP protocol layer (Unit + Integration)
├── ExcelMcp.CLI.Tests/        # CLI wrapper (Unit + Integration)
└── ExcelMcp.ComInterop.Tests/ # COM utilities (Unit + OnDemand)

Test Categories

Category	Speed	Requirements	Run By Default
Unit	Fast (2-5 sec)	None	✅ Yes (CI/CD)
Integration	Medium (10-20 min)	Excel + Windows	✅ Yes (local)
OnDemand	Slow (3-5 min)	Excel + Windows	❌ No (explicit only)

Feature-Specific Tests

# Test specific feature only
dotnet test --filter "Feature=PowerQuery&RunType!=OnDemand"
dotnet test --filter "Feature=DataModel&RunType!=OnDemand"
dotnet test --filter "Feature=Tables&RunType!=OnDemand"
dotnet test --filter "Feature=PivotTables&RunType!=OnDemand"
dotnet test --filter "Feature=Ranges&RunType!=OnDemand"
dotnet test --filter "Feature=Connections&RunType!=OnDemand"

When to Run Which Tests

Scenario	Command
Daily development	`dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA"`
Before commit	`dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA"`
Modified session/batch code	`dotnet test --filter "RunType=OnDemand"` (see Rule 3)
VBA development	`dotnet test --filter "(Feature=VBA\|Feature=VBATrust)&RunType!=OnDemand"`

VBA Testing

Why VBA Tests Are Excluded by Default

VBA tests are excluded from normal test runs because:

Stable codebase - VBA features are mature with minimal changes
Performance - Excluding VBA tests makes integration tests ~25% faster (10-15 min vs 15-20 min)
Special requirements - VBA tests require VBA trust enabled in Excel settings
Opt-in model - Explicit testing when VBA code changes, rather than every commit

When to Run VBA Tests

Run VBA tests manually when:

Modifying VBA-related code (ScriptCommands, VbaTrustDetection)
Adding new VBA features
Before releasing VBA-related changes
Troubleshooting VBA-specific issues

How to Run VBA Tests

# Run ONLY VBA tests
dotnet test --filter "(Feature=VBA|Feature=VBATrust)&RunType!=OnDemand"

# Run ALL tests including VBA (takes longer)
dotnet test --filter "Category=Integration&RunType!=OnDemand"

VBA Test Files

All VBA tests are tagged with [Trait("Feature", "VBA")] or [Trait("Feature", "VBATrust")]:

tests/ExcelMcp.Core.Tests/Integration/Commands/Script/
  - ScriptCommandsTests.cs
  - ScriptCommandsTests.Lifecycle.cs
  - VbaTrustDetectionTests.ScriptCommands.cs
  - VbaTrustDetectionTests.cs

tests/ExcelMcp.CLI.Tests/Integration/Commands/
  - ScriptAndSetupCommandsTests.cs

VBA Trust Setup

VBA tests require VBA trust enabled in Excel:

# Enable VBA trust (required for VBA tests)
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Office\16.0\Excel\Security" -Name "AccessVBOM" -Value 1

# Verify setting
Get-ItemProperty -Path "HKCU:\Software\Microsoft\Office\16.0\Excel\Security" -Name "AccessVBOM"

Security Note: Only enable VBA trust in development environments. Production systems should keep this disabled.

Key Principles

✅ File Isolation - Each test creates unique file (no sharing)
✅ Binary Assertions - Pass OR fail, never "accept both"
✅ Verify Excel State - Always verify actual Excel state after operations
❌ No SaveAsync - Unless testing persistence (see Rule 14)

Getting Help

Test failures: Check test output for detailed error messages
Excel issues: Ensure Excel 2016+ installed and activated
Session/batch issues: Run OnDemand tests to verify cleanup
Writing tests: See Testing Strategy