# 测试方案设计

> 所属项目: free-code .NET 10 重写
> 文档类型: 测试设计
> 来源章节: DESIGN-NET10-PART3.md § 22
> 上级文档: [测试与构建总览](测试与构建.md)

---

## 概述

原始 TypeScript 项目没有系统化的测试覆盖。.NET 重写从零建立分层测试体系，目标是核心路径 80%+ 覆盖率。测试框架组合为 **xUnit 2 + NSubstitute 5 + FluentAssertions 7**，三个独立测试项目分别承载单元、集成和 E2E 三个层次。

---

## 22.1 测试项目结构

```
tests/
├── FreeCode.Tests.Unit/           # 120+ 单元测试
│   ├── Engine/
│   │   ├── QueryEngineTests.cs
│   │   └── SystemPromptBuilderTests.cs
│   ├── Tools/
│   │   ├── BashToolTests.cs
│   │   ├── FileEditToolTests.cs
│   │   ├── FileReadToolTests.cs
│   │   ├── FileWriteToolTests.cs
│   │   ├── GlobToolTests.cs
│   │   ├── GrepToolTests.cs
│   │   ├── AgentToolTests.cs
│   │   └── ToolRegistryTests.cs
│   ├── Commands/
│   │   └── CommandRegistryTests.cs
│   ├── ApiProviders/
│   │   ├── AnthropicProviderTests.cs
│   │   ├── CodexProviderTests.cs
│   │   └── ProviderRouterTests.cs
│   ├── Mcp/
│   │   ├── McpClientTests.cs
│   │   ├── McpClientManagerTests.cs
│   │   └── TransportTests.cs
│   ├── Lsp/
│   │   └── LspClientManagerTests.cs
│   ├── Services/
│   │   ├── AuthServiceTests.cs
│   │   ├── RateLimitServiceTests.cs
│   │   ├── SessionMemoryServiceTests.cs
│   │   ├── CompanionServiceTests.cs
│   │   └── NotificationServiceTests.cs
│   └── State/
│       └── AppStateStoreTests.cs
├── FreeCode.Tests.Integration/    # 60 集成测试
│   ├── QueryPipelineTests.cs
│   ├── McpIntegrationTests.cs
│   ├── LspIntegrationTests.cs
│   ├── BridgeIntegrationTests.cs
│   ├── TaskManagerTests.cs
│   └── PluginLoadingTests.cs
└── FreeCode.Tests.E2E/            # 20 端到端测试
    ├── CliTests.cs
    ├── OneShotModeTests.cs
    └── InteractiveReplTests.cs
```

---

## 22.2 单元测试示例

### BashToolTests.cs

测试覆盖: 命令执行、超时处理、后台任务、只读分类。
原始来源: `../../src/tools/BashTool.tsx`

```csharp
// === BashToolTests.cs ===
public class BashToolTests
{
    private readonly BashTool _tool = new(
        Substitute.For<IBackgroundTaskManager>(),
        Substitute.For<IFeatureFlagService>());

    [Fact]
    public async Task ExecuteAsync_SimpleCommand_ReturnsOutput()
    {
        // Arrange
        var input = new BashToolInput { Command = "echo hello" };
        var context = new ToolExecutionContext(
            WorkingDirectory: Path.GetTempPath(),
            PermissionMode: PermissionMode.Default,
            AdditionalWorkingDirectories: [],
            PermissionEngine: Substitute.For<IPermissionEngine>(),
            LspManager: Substitute.For<ILspClientManager>(),
            TaskManager: Substitute.For<IBackgroundTaskManager>(),
            Services: Substitute.For<IServiceProvider>());

        // Act
        var result = await _tool.ExecuteAsync(input, context);

        // Assert
        result.IsError.Should().BeFalse();
        result.Data.Stdout.Trim().Should().Be("hello");
        result.Data.ExitCode.Should().Be(0);
    }

    [Fact]
    public async Task ExecuteAsync_Timeout_KillsProcess()
    {
        var input = new BashToolInput { Command = "sleep 10", Timeout = 500 };
        var context = CreateContext();

        var result = await _tool.ExecuteAsync(input, context);

        result.Data.Interrupted.Should().BeTrue();
        result.Data.ExitCode.Should().Be(-1);
    }

    [Fact]
    public async Task ExecuteAsync_Background_ReturnsTaskId()
    {
        var taskManager = Substitute.For<IBackgroundTaskManager>();
        taskManager.CreateShellTaskAsync(Arg.Any<string>(), Arg.Any<ProcessStartInfo>())
            .Returns(new LocalShellTask { TaskId = "bg-123", Command = "sleep 10" });

        var tool = new BashTool(taskManager, Substitute.For<IFeatureFlagService>());
        var input = new BashToolInput { Command = "sleep 10", RunInBackground = true };
        var result = await tool.ExecuteAsync(input, CreateContext());

        result.Data.BackgroundTaskId.Should().Be("bg-123");
    }

    [Theory]
    [InlineData("ls", true)]
    [InlineData("rm -rf /", false)]
    [InlineData("cat file.txt", true)]
    [InlineData("echo test > file", false)]
    public void IsReadOnly_ClassifiesCorrectly(string command, bool expected)
    {
        var input = new BashToolInput { Command = command };
        _tool.IsReadOnly(input).Should().Be(expected);
    }
}
```

---

### ToolRegistryTests.cs

测试覆盖: 基础工具注册、MCP 工具去重策略。
原始来源: `../../src/tools.ts`

```csharp
// === ToolRegistryTests.cs ===
public class ToolRegistryTests
{
    [Fact]
    public async Task GetToolsAsync_ReturnsBaseTools()
    {
        var registry = CreateRegistry();
        var tools = await registry.GetToolsAsync();

        tools.Should().Contain(t => t.Name == "Read");
        tools.Should().Contain(t => t.Name == "Edit");
        tools.Should().Contain(t => t.Name == "Bash");
        tools.Should().Contain(t => t.Name == "Agent");
    }

    [Fact]
    public async Task AssembleToolPool_DeduplicatesMcpTools()
    {
        // 内置 "Bash" 工具 + MCP 也提供 "Bash" → 只保留内置
        var registry = CreateRegistry();
        var mcpManager = Substitute.For<IMcpClientManager>();
        mcpManager.GetToolsAsync().Returns(new List<ITool>
        {
            CreateTool("Bash"),        // 与内置重名，应被丢弃
            CreateTool("SlackSearch"), // 新工具，应被添加
        });

        // 验证: Bash 只有一个 (内置), SlackSearch 被添加
    }
}
```

---

### AnthropicProviderTests.cs

测试覆盖: SSE 流式事件解析。
原始来源: `../../src/services/api/claude.ts`

```csharp
// === AnthropicProviderTests.cs ===
public class AnthropicProviderTests
{
    [Fact]
    public async Task StreamAsync_ParsesSSECorrectly()
    {
        var sseResponse = "event: message_start\ndata: {\"type\":\"message_start\"}\n\n"
            + "event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"delta\":{\"text\":\"Hello\"}}\n\n"
            + "event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n";

        var handler = new MockHttpHandler(sseResponse);
        var provider = new AnthropicProvider(new HttpClient(handler));

        var messages = new List<SDKMessage>();
        await foreach (var msg in provider.StreamAsync(new ApiRequest()))
            messages.Add(msg);

        messages.Should().ContainSingle(m => m is SDKMessage.StreamingDelta sd && sd.Text == "Hello");
    }
}
```

---

### CompanionServiceTests.cs

测试覆盖: 骰子结果确定性、不同用户产生不同结果。
原始来源: 无直接对应（新增 Companion 功能）

```csharp
// === CompanionServiceTests.cs ===
public class CompanionServiceTests
{
    [Fact]
    public void RollBones_IsDeterministic()
    {
        // 相同 userId → 相同骨骼
        var service = new CompanionService(Substitute.For<IGlobalConfig>());
        var c1 = service.RollBones("user-123");
        var c2 = service.RollBones("user-123");
        c1.Should().BeEquivalentTo(c2);
    }

    [Fact]
    public void RollBones_DifferentUsers_DifferentResults()
    {
        var service = new CompanionService(Substitute.For<IGlobalConfig>());
        var c1 = service.RollBones("user-A");
        var c2 = service.RollBones("user-B");
        // 极大概率不同 (18 种族, 6 眼形, 5 稀有度)
        (c1.Species != c2.Species || c1.Eye != c2.Eye).Should().BeTrue();
    }
}
```

---

## 22.3 集成测试示例

### McpIntegrationTests.cs

测试覆盖: stdio MCP 服务器连接建立。
原始来源: `../../src/services/mcp/`

```csharp
// === McpIntegrationTests.cs ===
public class McpIntegrationTests : IAsyncLifetime
{
    private McpClientManager _manager = null!;
    private string _tempDir = null!;

    public async Task InitializeAsync()
    {
        _tempDir = Path.Combine(Path.GetTempPath(), $"mcp-test-{Guid.NewGuid():N}");
        Directory.CreateDirectory(_tempDir);

        // 创建一个测试用 MCP stdio 服务器脚本
        var serverScript = Path.Combine(_tempDir, "test-server.sh");
        await File.WriteAllTextAsync(serverScript, @"#!/bin/bash
echo '{""jsonrpc"":""2.0"",""id"":1,""result"":{""protocolVersion"":""2025-03-26"",""capabilities"":{""tools"":{}}}}'
");
        Process.Start("chmod", $"+x {serverScript}")?.WaitForExit();
    }

    [Fact]
    public async Task ConnectServersAsync_ConnectsToStdioServer()
    {
        // 配置一个 stdio MCP 服务器
        var config = new StdioServerConfig { Command = "echo", Scope = ConfigScope.Local };
        // ... 验证连接成功
    }
}
```

---

## 22.4 E2E 测试示例

### CliTests.cs

测试覆盖: 版本标志输出、一次性模式响应。
原始来源: `../../src/entrypoints/cli.tsx`

```csharp
// === CliTests.cs ===
public class CliTests
{
    [Fact]
    public async Task VersionFlag_PrintsVersion()
    {
        var result = await RunCliAsync("--version");
        result.ExitCode.Should().Be(0);
        result.Output.Should().StartWith("free-code ");
    }

    [Fact]
    public async Task OneShotMode_ReturnsResponse()
    {
        // 需要 mock API server
        var result = await RunCliAsync("-p", "what is 2+2?");
        result.ExitCode.Should().Be(0);
    }

    private static async Task<(int ExitCode, string Output)> RunCliAsync(params string[] args)
    {
        using var process = new Process
        {
            StartInfo = new ProcessStartInfo
            {
                FileName = "dotnet",
                Arguments = $"run --project src/FreeCode {string.Join(" ", args)}",
                RedirectStandardOutput = true,
                RedirectStandardError = true,
                CreateNoWindow = true,
            }
        };
        process.Start();
        var output = await process.StandardOutput.ReadToEndAsync();
        await process.WaitForExitAsync();
        return (process.ExitCode, output);
    }
}
```

---

## 22.5 测试金字塔

| 层次 | 项目 | 数量 | 执行时间目标 |
|------|------|------|------------|
| 单元测试 | `FreeCode.Tests.Unit` | 120+ | < 30 秒 |
| 集成测试 | `FreeCode.Tests.Integration` | 60 | < 3 分钟 |
| E2E 测试 | `FreeCode.Tests.E2E` | 20 | < 10 分钟 |
| **合计** | | **200** | |

单元测试覆盖所有工具、引擎、命令、API 提供商、MCP/LSP 客户端、服务层和状态管理。集成测试验证跨组件交互（查询管道、MCP 连接、LSP 通信、Bridge 握手、任务管理器、插件加载）。E2E 测试启动完整进程，验证 CLI 行为对外部用户可见的部分。

---

## 22.6 测试框架版本

| 包 | 版本 | 用途 |
|----|------|------|
| `xunit` | 2.x | 测试运行器和断言基础 |
| `NSubstitute` | 5.x | 接口 mock / stub / spy |
| `FluentAssertions` | 7.x | 可读的断言链 |
| `Microsoft.NET.Test.Sdk` | 最新 | dotnet test 集成 |
| `coverlet.collector` | 最新 | 代码覆盖率收集 |

---

## 参考资料

- [测试与构建总览](测试与构建.md)
- [原始代码映射 — 测试与构建](reference/原始代码映射-测试与构建.md)
- [核心模块设计 — 工具系统](../核心模块设计/核心模块设计-工具系统.md)
- [基础设施设计](../基础设施设计/基础设施设计.md)