lsp-hover-testing

Automated headless testing of LSP hover functionality for the Dingo transpiler. Replaces manual VS Code hover checks with reproducible, CI-compatible tests.

When to Use This Skill

• After making changes to sourcemap/position tracking code
• When debugging hover issues reported by users
• To validate that column/line mappings work correctly
• Before committing changes to pkg/lsp/, pkg/sourcemap/, or pkg/transpiler/
• To create regression tests for hover functionality

Quick Start

# Build the tools first
go build -o dingo ./cmd/dingo
go build -o editors/vscode/server/bin/dingo-lsp ./cmd/dingo-lsp
go build -o lsp-hovercheck ./cmd/lsp-hovercheck

# Run hover tests
./lsp-hovercheck --spec "ai-docs/hover-specs/*.yaml"

# Verbose output for debugging
./lsp-hovercheck --spec ai-docs/hover-specs/http_handler.yaml --verbose

Spec File Format

Create YAML specs in ai-docs/hover-specs/:

file: examples/01_error_propagation/http_handler.dingo

cases:
  - id: 1
    line: 55                    # 1-based line number
    token: userID               # Token to hover on
    occurrence: 1               # Which occurrence (default: 1)
    description: "LHS variable"
    expect:
      contains: "var userID string"      # Must contain substring
      # OR
      containsAny:                        # Any of these
        - "var userID"
        - "userID string"
      # OR
      allowAny: true                      # Accept any result (skip assertion)

Assertion Types

| Type | Description | Example | |------|-------------|---------| | contains | Must contain substring | contains: "func foo" | | containsAny | Any of listed substrings | containsAny: ["func", "method"] | | notContains | Must not contain | notContains: "error" | | allowAny | Skip assertion, just record | allowAny: true |

Output Format

http_handler.yaml:
------------------------------------------------------------
1: works
2: works
3: expected "var r", got "func extractUserID..."
4: works

============================================================
Total: 3 passed, 1 failed

Creating New Test Specs

Step 1: Identify test positions

# Show line numbers
sed -n '50,70p' examples/01_error_propagation/http_handler.dingo | nl -ba

Step 2: Create spec file

cat > ai-docs/hover-specs/my_example.yaml << 'EOF'
file: examples/my_example/file.dingo

cases:
  - id: 1
    line: 10
    token: myFunction
    description: "Function name hover"
    expect:
      contains: "func myFunction"
EOF

Step 3: Run and iterate

./lsp-hovercheck --spec ai-docs/hover-specs/my_example.yaml --verbose

Debugging Failed Tests

When a test fails, check:

1. Column position: Is the token found at the right column?
2. Tab handling: Lines starting with tabs may have offset issues
3. Transformed lines: Error prop lines map to different Go positions
4. LSP readiness: Increase --retries if hover returns empty

Verbose debug output

./lsp-hovercheck --spec ai-docs/hover-specs/http_handler.yaml --verbose

Shows:

• Exact LSP request/response JSON
• Computed column positions
• Hover content returned

Known Limitations

VS Code vs Automated Differences

The automated test may show different results than VS Code due to:

• Tab character handling differences
• LSP initialization timing
• VS Code extension preprocessing

Current Behavior (2025-12-14)

| Position Type | Automated Result | VS Code Result | |--------------|------------------|----------------| | Function names | Works | Works | | Function arguments | Works | Shows function sig (bug) | | LHS variables | Empty | Shows temp var (bug) |

File Locations

| File | Purpose | |------|---------| | cmd/lsp-hovercheck/ | Hover check tool source | | ai-docs/hover-specs/ | Test specification files | | editors/vscode/server/bin/dingo-lsp | LSP server binary |

CI Integration

Add to your CI pipeline:

- name: Build tools
  run: |
    go build -o dingo ./cmd/dingo
    go build -o editors/vscode/server/bin/dingo-lsp ./cmd/dingo-lsp
    go build -o lsp-hovercheck ./cmd/lsp-hovercheck

- name: Run hover tests
  run: ./lsp-hovercheck --spec "ai-docs/hover-specs/*.yaml"

Related Files

• Spec format reference
• Debugging guide