# Lsp Hover Testing

> Lsp Hover Testing is an Agent Skill for testing & quality published in the MadAppGang/dingo repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Automated LSP hover validation for Dingo transpiler. Use when testing hover functionality, validating position mappings, checking for hover drift, or debugging LSP issues after sourcemap changes.

- Skill name: `lsp-hover-testing`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/MadAppGang/dingo/blob/HEAD/.claude/skills/lsp-hover-testing/SKILL.md
- Repository: MadAppGang/dingo (1,902 GitHub stars when collected)

## SKILL.md

# LSP Hover Testing Skill

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

```bash
# 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/`:

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

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

### Step 2: Create spec file

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

```bash
./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

```bash
./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:

```yaml
- 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](SPEC_FORMAT.md)
- [Debugging guide](DEBUGGING.md)

---

Source: https://www.openparable.com/skill/testing-quality/lsp-hover-testing (OpenParable). Cite the canonical URL above.
