测试

为什么要测试 Vapor 应用？

服务端应用由路由、中间件、数据库操作、业务逻辑组成，各层相互依赖。没有自动化测试，每次修改都可能无声地破坏某个接口；有了测试，改动后只需运行一条命令，就能确认所有契约仍然有效。

Vapor 应用的测试通常分为两个层次：

XCTVapor 的设计思路是：在内存中启动一个真实的 Vapor 应用实例（不监听任何端口），然后通过 testable() 方法直接把 HTTP 请求注入进去，绕过网络栈，同时保留完整的业务逻辑链路。这既有集成测试的覆盖深度，又避免了真实 HTTP 的开销和不确定性。

XCTVapor 核心概念

测试环境配置

XCTVapor 已包含在 Vapor 核心包内，但需要在 Package.swift 中显式将它添加为测试 Target 的依赖，避免把测试代码打包进生产二进制文件：

// Package.swift
// swift-tools-version:6.0
import PackageDescription

let package = Package(
    name: "MyVaporApp",
    platforms: [.macOS(.v14)],
    // Swift 6 严格并发检查
    swiftLanguageVersions: [.v6],
    dependencies: [
        .package(url: "https://github.com/vapor/vapor.git", from: "4.99.0"),
        .package(url: "https://github.com/vapor/fluent.git", from: "4.9.0"),
        .package(url: "https://github.com/vapor/fluent-sqlite-driver.git", from: "4.6.0"),
    ],
    targets: [
        .executableTarget(
            name: "App",
            dependencies: [
                .product(name: "Vapor",  package: "vapor"),
                .product(name: "Fluent", package: "fluent"),
            ]
        ),
        .testTarget(
            name: "AppTests",
            dependencies: [
                .target(name: "App"),
                // XCTVapor 只在测试 Target 引入
                .product(name: "XCTVapor",             package: "vapor"),
                // 内存 SQLite 用于测试数据库
                .product(name: "FluentSQLiteDriver", package: "fluent-sqlite-driver"),
            ]
        ),
    ]
)

每个测试类都需要创建一个独立的 Application 实例，并在测试结束时关闭它。推荐封装成一个辅助函数，供所有测试用例复用：

// Tests/AppTests/Helpers/makeTestApp.swift
import XCTest
import XCTVapor
import FluentSQLiteDriver
@testable import App

/// 创建一个隔离的测试应用实例
/// - Parameter configure: 额外的配置闭包（可选）
func makeTestApp(
    _ configure: ((Application) throws -> Void)? = nil
) async throws -> Application {
    // 使用 .testing 环境（不绑定端口）
    let app = try await Application.make(.testing)

    // 注册内存 SQLite 数据库（每次测试都是空库）
    app.databases.use(.sqlite(.memory), as: .sqlite)

    // 注册 Migrations
    app.migrations.add(CreateUser())
    app.migrations.add(CreatePost())

    // 运行迁移（创建空表）
    try await app.autoMigrate()

    // 注册路由
    try routes(app)

    // 允许调用方追加额外配置
    try configure?(app)

    return app
}

第一个集成测试

假设应用有一个健康检查接口 GET /health，返回 {"status": "ok"}。下面写第一个端到端测试，验证状态码和响应体：

// Tests/AppTests/HealthTests.swift
import XCTest
import XCTVapor
@testable import App

final class HealthTests: XCTestCase {

    var app: Application!

    @MainActor
    override func setUp() async throws {
        app = try await makeTestApp()
    }

    @MainActor
    override func tearDown() async throws {
        // 关闭应用，释放数据库连接等资源
        try await app.asyncShutdown()
        app = nil
    }

    func testHealthEndpoint() async throws {
        try await app.test(.GET, "/health") { res async throws in
            // 1. 验证 HTTP 状态码
            XCTAssertEqual(res.status, .ok)

            // 2. 验证 Content-Type
            XCTAssertEqual(
                res.headers.contentType,
                .init(type: "application", subType: "json")
            )

            // 3. 将 JSON 响应体解码为 Swift 结构体
            struct HealthResponse: Decodable {
                let status: String
            }
            let body = try res.content.decode(HealthResponse.self)
            XCTAssertEqual(body.status, "ok")
        }
    }

    func testNotFound() async throws {
        // 访问不存在的路由应该返回 404
        try await app.test(.GET, "/nonexistent") { res async throws in
            XCTAssertEqual(res.status, .notFound)
        }
    }
}

测试数据库（内存 SQLite）

集成测试中最大的挑战是数据库：我们既不能污染生产数据库，也不能依赖已有的数据状态。解决方案是为每个测试用例使用独立的内存 SQLite 数据库。SQLite 的 :memory: 模式会在内存中创建一个完全独立的数据库，进程结束后自动消失，零配置，跨平台：

// Tests/AppTests/UserTests.swift
import XCTest
import XCTVapor
import Fluent
@testable import App

final class UserTests: XCTestCase {

    var app: Application!

    @MainActor
    override func setUp() async throws {
        app = try await makeTestApp()
        // 此时数据库中 users 表已存在但完全为空
    }

    @MainActor
    override func tearDown() async throws {
        // autoRevert() 会删除所有表，再 asyncShutdown() 关闭连接池
        try await app.autoRevert()
        try await app.asyncShutdown()
        app = nil
    }

    // 辅助方法：在数据库中创建一条测试用户记录
    func createTestUser(
        name: String  = "Alice",
        email: String = "alice@example.com"
    ) async throws -> User {
        let user = User(name: name, email: email, passwordHash: "hash")
        try await user.save(on: app.db)
        return user
    }
}

测试完整 CRUD API

一个典型的 REST 资源接口包含创建、列表、单条查询、更新、删除五个操作。为每一个操作写独立的测试方法，使每个测试都聚焦于单一职责，失败时立刻知道哪个操作出了问题：

// Tests/AppTests/PostCRUDTests.swift
final class PostCRUDTests: XCTestCase {

    var app: Application!

    @MainActor
    override func setUp() async throws {
        app = try await makeTestApp()
    }

    @MainActor
    override func tearDown() async throws {
        try await app.autoRevert()
        try await app.asyncShutdown()
        app = nil
    }

    // POST /posts — 创建文章
    func testCreatePost() async throws {
        struct CreatePostDTO: Content {
            var title: String
            var body:  String
        }
        let dto = CreatePostDTO(title: "测试标题", body: "测试内容")

        try await app.test(.POST, "/posts",
            beforeRequest: { req async throws in
                try req.content.encode(dto, as: .json)
            },
            afterResponse: { res async throws in
                XCTAssertEqual(res.status, .created)
                let post = try res.content.decode(Post.self)
                XCTAssertEqual(post.title, "测试标题")
                XCTAssertEqual(post.body,  "测试内容")
                // 服务端生成的 UUID 不应为 nil
                XCTAssertNotNil(post.id)
            }
        )
    }

    // GET /posts — 列表查询
    func testListPosts() async throws {
        // 预先向数据库写入两条记录
        let p1 = Post(title: "文章 A", body: "内容 A")
        let p2 = Post(title: "文章 B", body: "内容 B")
        try await [p1, p2].create(on: app.db)

        try await app.test(.GET, "/posts") { res async throws in
            XCTAssertEqual(res.status, .ok)
            let posts = try res.content.decode([Post].self)
            XCTAssertEqual(posts.count, 2)
        }
    }

    // GET /posts/:id — 单条查询
    func testGetPostByID() async throws {
        let post = Post(title: "唯一文章", body: "正文")
        try await post.save(on: app.db)
        let id = try post.requireID()

        try await app.test(.GET, "/posts/\(id)") { res async throws in
            XCTAssertEqual(res.status, .ok)
            let fetched = try res.content.decode(Post.self)
            XCTAssertEqual(fetched.title, "唯一文章")
        }
    }

    // PUT /posts/:id — 更新文章
    func testUpdatePost() async throws {
        let post = Post(title: "旧标题", body: "旧内容")
        try await post.save(on: app.db)
        let id = try post.requireID()

        struct UpdateDTO: Content {
            var title: String
            var body:  String
        }
        let update = UpdateDTO(title: "新标题", body: "新内容")

        try await app.test(.PUT, "/posts/\(id)",
            beforeRequest: { req async throws in
                try req.content.encode(update, as: .json)
            },
            afterResponse: { res async throws in
                XCTAssertEqual(res.status, .ok)
                let updated = try res.content.decode(Post.self)
                XCTAssertEqual(updated.title, "新标题")
            }
        )
    }

    // DELETE /posts/:id — 删除文章
    func testDeletePost() async throws {
        let post = Post(title: "待删除", body: "内容")
        try await post.save(on: app.db)
        let id = try post.requireID()

        try await app.test(.DELETE, "/posts/\(id)") { res async throws in
            XCTAssertEqual(res.status, .noContent)  // 204
        }

        // 再查询应该返回 404
        try await app.test(.GET, "/posts/\(id)") { res async throws in
            XCTAssertEqual(res.status, .notFound)
        }
    }

    // 边界情况：请求不存在的 ID 应该返回 404
    func testGetNonexistentPost() async throws {
        let fakeID = UUID()
        try await app.test(.GET, "/posts/\(fakeID)") { res async throws in
            XCTAssertEqual(res.status, .notFound)
        }
    }
}

Test Double 模式

集成测试覆盖了 HTTP 路由和数据库，但当 Handler 调用外部服务时（发送邮件、调用第三方 API、上传文件到 S3），直接在测试中触发这些操作既慢又不可靠。Test Double（测试替身）的思路是：用协议定义服务接口，在测试中注入假实现（Mock/Stub），在生产中注入真实实现。

// Sources/App/Services/EmailService.swift

/// 邮件服务接口（协议）
protocol EmailService: Sendable {
    func sendWelcome(to email: String, name: String) async throws
    func sendPasswordReset(to email: String, token: String) async throws
}

/// 生产实现（调用真实 SMTP）
struct SMTPEmailService: EmailService {
    let host:   String
    let apiKey: String

    func sendWelcome(to email: String, name: String) async throws {
        // 真实的 SMTP 发送逻辑...
    }

    func sendPasswordReset(to email: String, token: String) async throws {
        // 真实的 SMTP 发送逻辑...
    }
}

// 通过 Application.Storage 注入服务
extension Application {
    private struct EmailServiceKey: StorageKey {
        typealias Value = any EmailService
    }

    var emailService: any EmailService {
        get { storage[EmailServiceKey.self]! }
        set { storage[EmailServiceKey.self] = newValue }
    }
}

// Tests/AppTests/Mocks/MockEmailService.swift

/// 测试用假邮件服务——记录调用，但不真正发邮件
actor MockEmailService: EmailService {

    private(set) var sentEmails: [(to: String, subject: String)] = []

    func sendWelcome(to email: String, name: String) async throws {
        // 记录调用而非真正发送
        sentEmails.append((to: email, subject: "welcome"))
    }

    func sendPasswordReset(to email: String, token: String) async throws {
        sentEmails.append((to: email, subject: "reset"))
    }

    var callCount: Int { sentEmails.count }
}

// Tests/AppTests/UserRegistrationTests.swift
final class UserRegistrationTests: XCTestCase {

    var app:       Application!
    var mockEmail: MockEmailService!

    @MainActor
    override func setUp() async throws {
        mockEmail = MockEmailService()

        app = try await makeTestApp { app in
            // 注入假邮件服务，覆盖生产配置
            app.emailService = mockEmail
        }
    }

    @MainActor
    override func tearDown() async throws {
        try await app.asyncShutdown()
    }

    func testRegisterSendsWelcomeEmail() async throws {
        struct RegisterDTO: Content {
            var name:     String
            var email:    String
            var password: String
        }
        let dto = RegisterDTO(
            name:     "Bob",
            email:    "bob@example.com",
            password: "secret123"
        )

        try await app.test(.POST, "/auth/register",
            beforeRequest: { req async throws in
                try req.content.encode(dto)
            },
            afterResponse: { res async throws in
                XCTAssertEqual(res.status, .created)
            }
        )

        // 验证邮件服务被调用了恰好一次
        let count = await mockEmail.callCount
        XCTAssertEqual(count, 1)

        let emails = await mockEmail.sentEmails
        XCTAssertEqual(emails.first?.to,      "bob@example.com")
        XCTAssertEqual(emails.first?.subject, "welcome")
    }
}

认证测试

JWT 保护的路由在没有有效令牌的情况下应返回 401，在令牌有效时正常响应。测试这类路由的关键是：在 setUp 中生成一个专用于测试的 JWT 令牌，然后在 beforeRequest 闭包中将它写入 Authorization 请求头：

// Tests/AppTests/AuthenticatedRouteTests.swift
import XCTest
import XCTVapor
import JWT
@testable import App

final class AuthenticatedRouteTests: XCTestCase {

    var app:       Application!
    var testToken: String!

    @MainActor
    override func setUp() async throws {
        app = try await makeTestApp()

        // 创建一个测试用户并生成 JWT 令牌
        let user = User(
            name: "Tester",
            email: "test@example.com",
            passwordHash: "x"
        )
        try await user.save(on: app.db)
        let userID = try user.requireID()

        // 使用与生产相同的 JWT 签发逻辑
        let payload = UserPayload(
            subject:    .init(value: userID.uuidString),
            expiration: .init(value: .distantFuture),
            userID:     userID
        )
        testToken = try await app.jwt.keys.sign(payload)
    }

    @MainActor
    override func tearDown() async throws {
        try await app.asyncShutdown()
    }

    // 无 Token — 应该返回 401
    func testProtectedRouteRequiresAuth() async throws {
        try await app.test(.GET, "/api/me") { res async throws in
            XCTAssertEqual(res.status, .unauthorized)
        }
    }

    // 携带有效 Token — 应该返回 200
    func testProtectedRouteWithValidToken() async throws {
        try await app.test(.GET, "/api/me",
            beforeRequest: { req async throws in
                // 在 Authorization 请求头中携带 Bearer Token
                req.headers[.authorization] = "Bearer \(self.testToken!)"
            },
            afterResponse: { res async throws in
                XCTAssertEqual(res.status, .ok)
                struct MeResponse: Decodable { let name: String }
                let me = try res.content.decode(MeResponse.self)
                XCTAssertEqual(me.name, "Tester")
            }
        )
    }

    // 过期 Token — 应该返回 401
    func testExpiredTokenIsRejected() async throws {
        // 签发一个已过期的令牌
        let expired = UserPayload(
            subject:    .init(value: "fake-user-id"),
            expiration: .init(value: Date(timeIntervalSinceNow: -3600)),
            userID:     UUID()
        )
        let expiredToken = try await app.jwt.keys.sign(expired)

        try await app.test(.GET, "/api/me",
            beforeRequest: { req async throws in
                req.headers[.authorization] = "Bearer \(expiredToken)"
            },
            afterResponse: { res async throws in
                XCTAssertEqual(res.status, .unauthorized)
            }
        )
    }
}

并发测试注意事项

Swift 6 引入了严格的 Actor 隔离检查，XCTest 在 Swift 6 中有一些需要特别注意的规则：

// Swift 6 正确的异步并发测试写法
final class ConcurrentTests: XCTestCase {

    var app: Application!

    @MainActor                          // ← 必须，保证 app 赋值在主 Actor
    override func setUp() async throws {
        app = try await makeTestApp()
    }

    @MainActor
    override func tearDown() async throws {
        try await app.asyncShutdown()
        app = nil
    }

    // 测试接口在并发读压力下的行为
    func testConcurrentReadRequests() async throws {
        // 预先插入共享数据
        let post = Post(title: "并发测试", body: "内容")
        try await post.save(on: app.db)
        let id = try post.requireID()

        // 并发发出 10 个只读请求，全部应该成功
        try await withThrowingTaskGroup(of: Void.self) { group in
            for _ in 0..<10 {
                group.addTask {
                    try await self.app.test(.GET, "/posts/\(id)") { res async throws in
                        XCTAssertEqual(res.status, .ok)
                    }
                }
            }
            try await group.waitForAll()
        }
    }
}

代码覆盖率

代码覆盖率（Code Coverage）衡量测试执行时实际运行了多少生产代码行。它不是衡量测试质量的唯一指标，但能帮助你发现明显的测试盲区——有些代码路径从未被任何测试触及。

# 运行测试并启用覆盖率收集
swift test --enable-code-coverage

# 查看生成的覆盖率数据文件
ls .build/debug/codecov/

# 用 llvm-cov 生成文本摘要报告
xcrun llvm-cov report \
    .build/debug/AppPackageTests.xctest/Contents/MacOS/AppPackageTests \
    -instr-profile=.build/debug/codecov/default.profdata \
    -ignore-filename-regex=".build|Tests"

# 生成可点击的 HTML 可视化报告
xcrun llvm-cov show \
    .build/debug/AppPackageTests.xctest/Contents/MacOS/AppPackageTests \
    -instr-profile=.build/debug/codecov/default.profdata \
    -format=html \
    -output-dir=coverage-report \
    -ignore-filename-regex=".build|Tests"

# 用浏览器打开报告
open coverage-report/index.html

除了命令行工具，xcov 是一个更友好的第三方覆盖率工具，可以生成精美报告并与 CI 集成，在覆盖率低于阈值时让构建失败：

# 安装 xcov（通过 Homebrew）
brew install xcov

# 在 Swift Package 项目中生成覆盖率报告
xcov \
    --scheme MyVaporApp \
    --output_directory coverage \
    --minimum_coverage_percentage 80.0

# 低于 80% 时 xcov 以非零退出码退出，CI 自动将构建标记为失败

# GitHub Actions 示例：在 CI 中收集覆盖率
# - name: Run tests with coverage
#   run: swift test --enable-code-coverage
# - name: Generate report
#   run: xcov --scheme MyVaporApp --minimum_coverage_percentage 80