# 构建与测试

开发并验证 LspCpp 本身变更的指南。

## 开发构建

```shell
mkdir _build && cd _build
cmake -DLSPCPP_BUILD_TESTS=ON ..
cmake --build . -j
```

`LSPCPP_BUILD_TESTS=ON` 会自动启用示例并注册全部 CTest target。
默认 `LSPCPP_BUILD_WEBSOCKETS=ON` 时当前注册 **25** 个 CTest 用例。`LSPCPP_BUILD_PERF_SMOKE=ON` 会添加 `lspcpp.perf_smoke`。

运行完整测试套件：

```shell
ctest --output-on-failure
```

运行单个测试：

```shell
ctest -R language_session --output-on-failure
```

或直接执行测试二进制（迭代更快）：

```shell
./lspcpp_language_session_tests
```

## 测试布局

测试是 `tests/` 中的独立可执行文件，不是单独的测试框架二进制。每个文件有 `main()`，运行命名测试函数，并通过 `tests/test_helpers.h` 报告失败。

| 测试二进制 | 重点 |
|------------|------|
| `lspcpp_language_session_tests` | `LanguageSession` API、生命周期、自定义解析器 |
| `lspcpp_remote_endpoint_tests` | `RemoteEndPoint` 分发与出站发送 |
| `lspcpp_jsonrpc_tests` | JSON-RPC 消息处理 |
| `lspcpp_stream_message_producer_tests` | 帧格式与流解析 |
| `lspcpp_endpoint_serializer_tests` | 序列化往返 |
| `lspcpp_infrastructure_tests` | 工具、Condition、流 |
| `lspcpp_working_files_tests` | 文档缓冲区管理 |
| `lspcpp_lsp_types_tests` | LSP 类型 JSON reflection |
| `lspcpp_protocol_json_handler_tests` | `ProtocolJsonHandler` 注册、allowlist 边界、golden LSP fixture |
| `lspcpp_clangd_fixture_tests` | clangd 衍生 golden fixture、session manifest、生命周期与错误码 |
| `lspcpp_lsp_3_16_17_tests` | 协议 3.16/3.17 类型 |
| `lspcpp_lsp_3_18_tests` | 协议 3.18 类型 |
| `lspcpp_tcp_write_queue_tests` | TCP 写队列 |
| `lspcpp_websocket_write_queue_tests` | WebSocket 写队列 |
| `lspcpp_api_compat_tests` | 可选取消、错误、Transport、请求上下文与 binder 兼容性 |
| `lspcpp_perf_smoke_tests` | 可选性能冒烟（默认关闭） |

共享辅助（`FeedableIStream`、`StringOStream`、`MakeLspFrame`）在 `tests/test_helpers.h`。
Protocol JSON 辅助（`ExpectParsesRequest`、`ExpectParsesResponse`、`ExpectParsesNotification`）在 `tests/protocol_test_helpers.h`。

## Protocol 覆盖策略

`ProtocolJsonHandler` 是 LSP method 的主要 wire-level 注册表。新增或修改已实现 LSP method 时：

1. 在 `src/lsp/ProtocolJsonHandler.cpp` 注册 request、response 或 notification parser。
2. 在 `tests/protocol_json_handler_tests.cpp`、`tests/lsp_types_roundtrip_tests.cpp` 或版本相关的 `tests/lsp_3_*_tests.cpp` 中添加/扩展解析断言。
3. 对用户可见或容易回归的 JSON 形状，在 `tests/fixtures/lsp/` 添加精简 golden 消息。
4. 不要把已实现 method 留在 `tools/lsp-metamodel-allowlist.json`。allowlist 表示“已知尚未实现”，不是“已实现但未测试”。

Protocol handler 测试会迭代当前已注册 parser map，并确认已注册 method 可用，且没有继续被 allowlist 标记为 missing。

以下为 consumer 项目与示例额外注册的 CTest 冒烟检查：

| CTest 名称 | 重点 |
|------------|------|
| `lspcpp.consumer_cmake_configure` | 配置示例 consumer 项目 |
| `lspcpp.consumer_cmake_build` | 从 consumer 构建构建 `consumer_smoke` 和 `MinimalStdIOServerExample` |
| `lspcpp.consumer_smoke_run` | 运行 consumer smoke 二进制 |
| `lspcpp.minimal_stdio_example_build` | 构建最小 stdio 示例 |
| `lspcpp.tcp_server_example` | 运行 TCP 示例冒烟测试 |
| `lspcpp.stdio_client_server_example` | 运行 stdio 客户端/服务器冒烟测试 |
| `lspcpp.websocket_example` | 启用 WebSocket 支持时运行 WebSocket 示例冒烟测试 |

## CMake consumer 测试

`tests/cmake/consumer_project/` 验证外部 CMake 项目能否通过 `add_subdirectory` 消费本源码树并链接 `lspcpp` target：

```shell
cmake -S tests/cmake/consumer_project -B _build_consumer \
  -DLSPCPP_SOURCE_DIR=/path/to/LspCpp
cmake --build _build_consumer
```

修改导出 target、target 名称或公共 `LibLsp/LspCpp.h` 入口时，请手动构建此测试。

## CI 配置

`.github/workflows/` 下的 GitHub Actions 工作流：

| 工作流 | 用途 |
|--------|------|
| `build-lsp-linux.yaml` | 使用 vcpkg preset 的 Linux 构建（C++17 含/不含 GC 矩阵，以及非 GC/非 WebSocket C++14 leg） |
| `build-lsp-windows.yaml` | Windows 构建 |
| `pull-req-precheck.yaml` | PR 验证 |
| `check-format-cpp.yaml` | clang-format 合规 |

本地 CI 等价构建：

```shell
export VCPKG_ROOT=/path/to/vcpkg
export LSPCPP_CI_VCPKG_FEATURES=tests
cmake --preset ci/default
cmake --build --preset ci/default -j
ctest --preset ci/default
```

C++14 兼容性验证（与 Linux 非 GC/非 WebSocket CI leg 一致）：

```shell
export VCPKG_ROOT=/path/to/vcpkg
export LSPCPP_CI_VCPKG_FEATURES=tests
cmake --preset ci/cpp14
cmake --build --preset ci/cpp14 -j
ctest --preset ci/cpp14 -R lspcpp --output-on-failure
```

## Sanitizer 构建

可选 sanitizer 标志，用于调试内存与线程问题：

| 选项 | Sanitizer |
|------|-----------|
| `LSPCPP_ASAN=ON` | AddressSanitizer |
| `LSPCPP_MSAN=ON` | MemorySanitizer |
| `LSPCPP_TSAN=ON` | ThreadSanitizer |

```shell
cmake -DLSPCPP_BUILD_TESTS=ON -DLSPCPP_ASAN=ON ..
cmake --build . -j
```

不要在同一构建中同时启用 ASAN 和 TSAN。

## 性能冒烟测试

```shell
cmake -DLSPCPP_BUILD_TESTS=ON -DLSPCPP_BUILD_PERF_SMOKE=ON ..
cmake --build . -j
ctest -R perf_smoke --output-on-failure
```

加上 `-DLSPCPP_PERF_WARNINGS_AS_ERRORS=ON` 可在性能警告时失败。

## Fuzzing

`LSPCPP_BUILD_FUZZER` 在 CMake 中声明为选项，但当前树尚未为其定义 fuzz target。在 CI 中依赖此选项前，需添加并文档化具体 target。

## 调试技巧

1. **使用 `StderrLog`** — 在示例或临时服务器中查看内部消息。
2. **运行单个测试二进制** — 按 `test_helpers.h` 风格添加临时 `Expect()` 调用。
3. **检查帧输出** — 测试通过 `StringOStream::snapshot()` 捕获 stdout；与预期 JSON 子串对比。
4. **编辑器 trace 日志** — 与真实编辑器集成时，开启 LSP trace，将 wire 格式与测试 fixture 对比。

## 添加新测试

1. 在 `tests/` 中创建或扩展文件。
2. 使用 `test::Expect(condition, "message")` 做断言；`test::Failures()` 返回失败计数。
3. 在 `CMakeLists.txt` 中注册可执行文件（参照现有 `add_executable` + `add_test` 块）。
4. 提交 PR 前运行 `ctest --output-on-failure`。