第 37 章：编写测试

// 文件：src/tools/testing/TestingPermissionTool.tsx
export const TestingPermissionTool: Tool<InputSchema, string> = buildTool({
  name: 'TestingPermission',
  isEnabled() {
    return "production" === 'test';  // 只有测试环境才启用
  },
  async checkPermissions() {
    return {
      behavior: 'ask' as const,
      message: 'Run test?'
    };
  },
  async call() {
    return { data: 'TestingPermission executed successfully' };
  },
})

// 文件：src/setup.ts
if (process.env.NODE_ENV === 'test') {
  // 测试环境下的特殊行为
}

// 文件：src/utils/debug.ts
if (process.env.NODE_ENV === 'test' && !isDebugToStderr()) {
  return false;  // 测试时不写 debug 日志
}

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    include: ['src/**/*.test.ts'],
  },
})

// 文件：src/tools/TimestampTool/TimestampTool.test.ts
import { describe, it, expect } from 'vitest'
import { z } from 'zod/v4'

const inputSchema = z.strictObject({
  format: z
    .enum(['iso', 'unix', 'locale'])
    .optional()
    .describe('Output format'),
})

describe('TimestampTool inputSchema', () => {
  it('接受无参数调用', () => {
    const result = inputSchema.safeParse({})
    expect(result.success).toBe(true)
  })

  it('接受 iso 格式', () => {
    const result = inputSchema.safeParse({ format: 'iso' })
    expect(result.success).toBe(true)
    if (result.success) {
      expect(result.data.format).toBe('iso')
    }
  })

  it('接受 unix 格式', () => {
    const result = inputSchema.safeParse({ format: 'unix' })
    expect(result.success).toBe(true)
  })

  it('拒绝非法格式', () => {
    const result = inputSchema.safeParse({ format: 'rfc2822' })
    expect(result.success).toBe(false)
  })

  it('拒绝额外字段（strictObject）', () => {
    const result = inputSchema.safeParse({ format: 'iso', extra: 'nope' })
    expect(result.success).toBe(false)
  })

  it('拒绝错误的类型', () => {
    const result = inputSchema.safeParse({ format: 123 })
    expect(result.success).toBe(false)
  })
})

import { describe, it, expect, vi } from 'vitest'

// 提取为纯函数便于测试
function formatTimestamp(format?: string): { timestamp: string; format: string } {
  const actualFormat = format ?? 'iso'
  switch (actualFormat) {
    case 'unix':
      return { timestamp: String(Math.floor(Date.now() / 1000)), format: 'unix' }
    case 'locale':
      return { timestamp: new Date().toLocaleString(), format: 'locale' }
    case 'iso':
    default:
      return { timestamp: new Date().toISOString(), format: 'iso' }
  }
}

describe('TimestampTool call 逻辑', () => {
  it('默认返回 ISO 格式', () => {
    const result = formatTimestamp()
    expect(result.format).toBe('iso')
    expect(result.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/)
  })

  it('返回 Unix 时间戳', () => {
    const result = formatTimestamp('unix')
    expect(result.format).toBe('unix')
    expect(result.timestamp).toMatch(/^\d+$/)
    expect(Number(result.timestamp)).toBeGreaterThan(1262304000)
  })

  it('使用固定时间来避免时区问题', () => {
    vi.useFakeTimers()
    vi.setSystemTime(new Date('2026-01-15T10:30:00.000Z'))

    const result = formatTimestamp('iso')
    expect(result.timestamp).toBe('2026-01-15T10:30:00.000Z')

    vi.useRealTimers()
  })
})

import { describe, it, expect, vi } from 'vitest'
import { readFile } from 'fs/promises'

// 模拟 fs.readFile
vi.mock('fs/promises', () => ({
  readFile: vi.fn(),
}))

describe('loadConfig', () => {
  it('解析合法的配置文件', async () => {
    vi.mocked(readFile).mockResolvedValue(
      JSON.stringify({ name: 'test', version: '1.0.0' })
    )

    const result = await loadConfig('/fake/path/config.json')

    expect(result).toEqual({ name: 'test', version: '1.0.0' })
    expect(readFile).toHaveBeenCalledWith('/fake/path/config.json', 'utf-8')
  })

  it('文件不存在时抛出错误', async () => {
    vi.mocked(readFile).mockRejectedValue(
      new Error('ENOENT: no such file or directory')
    )

    await expect(loadConfig('/no/such/file')).rejects.toThrow('ENOENT')
  })

  it('非法 JSON 时抛出错误', async () => {
    vi.mocked(readFile).mockResolvedValue('not json at all')

    await expect(loadConfig('/bad/config')).rejects.toThrow()
  })
})

describe('DBQueryTool checkPermissions', () => {
  const tool = new DBQueryTool()
  const mockContext = {} as ToolUseContext

  it('SELECT 查询自动放行', async () => {
    const result = await tool.checkPermissions(
      { query: 'SELECT * FROM users' },
      mockContext,
    )
    expect(result.behavior).toBe('allow')
  })

  it('DROP 操作直接拒绝', async () => {
    const result = await tool.checkPermissions(
      { query: 'DROP TABLE users' },
      mockContext,
    )
    expect(result.behavior).toBe('deny')
    expect(result.message).toContain('Destructive')
  })

  it('INSERT 操作需要确认', async () => {
    const result = await tool.checkPermissions(
      { query: 'INSERT INTO users VALUES (1, "test")' },
      mockContext,
    )
    expect(result.behavior).toBe('passthrough')
  })

  it('大小写不敏感', async () => {
    const result = await tool.checkPermissions(
      { query: 'select * from users' },
      mockContext,
    )
    expect(result.behavior).toBe('allow')
  })
})

describe('工具注册', () => {
  it('TimestampTool 出现在工具列表中', () => {
    const tools = getAllBaseTools()
    const names = tools.map(t => t.name)
    expect(names).toContain('Timestamp')
  })

  it('所有工具都有 name 属性', () => {
    const tools = getAllBaseTools()
    for (const tool of tools) {
      expect(tool.name).toBeTruthy()
      expect(typeof tool.name).toBe('string')
    }
  })

  it('所有工具都有 inputSchema', () => {
    const tools = getAllBaseTools()
    for (const tool of tools) {
      expect(tool.inputSchema).toBeDefined()
    }
  })

  it('工具名不重复', () => {
    const tools = getAllBaseTools()
    const names = tools.map(t => t.name)
    const uniqueNames = new Set(names)
    expect(uniqueNames.size).toBe(names.length)
  })
})

it('测试 async generator 工具', async () => {
  const results = []
  for await (const item of tool.call(input, context, canUseTool, message)) {
    results.push(item)
  }
  expect(results).toHaveLength(1)
  expect(results[0].data).toBeDefined()
})