claude-code/docs/test-plans/09-config-settings.md

配置系统测试计划

概述

配置系统包含全局配置（GlobalConfig）、项目配置（ProjectConfig）和设置（Settings）三层。测试重点是纯函数校验逻辑、Zod schema 验证和配置合并策略。

被测文件

文件	关键导出
src/utils/config.ts	getGlobalConfig, saveGlobalConfig, getCurrentProjectConfig, checkHasTrustDialogAccepted, isPathTrusted, getOrCreateUserID, isAutoUpdaterDisabled
src/utils/settings/settings.ts	getSettingsForSource, parseSettingsFile, getSettingsFilePathForSource, getInitialSettings
src/utils/settings/types.ts	SettingsSchema（Zod schema）
src/utils/settings/validation.ts	设置验证函数
src/utils/settings/constants.ts	设置常量

---

测试用例

src/utils/config.ts — 纯函数/常量

describe('DEFAULT_GLOBAL_CONFIG')

• test('has all required fields') — 默认配置对象包含所有必需字段
• test('has null auth fields by default') — oauthAccount 等为 null

describe('DEFAULT_PROJECT_CONFIG')

• test('has empty allowedTools') — 默认为空数组
• test('has empty mcpServers') — 默认为空对象

describe('isAutoUpdaterDisabled')

• test('returns true when CLAUDE_CODE_DISABLE_AUTOUPDATER is set') — env 设置时禁用
• test('returns true when disableAutoUpdater config is true')
• test('returns false by default')

---

src/utils/config.ts — 需 Mock

describe('getGlobalConfig')

• test('returns cached config on subsequent calls') — 缓存机制
• test('returns TEST_GLOBAL_CONFIG_FOR_TESTING in test mode')
• test('reads config from ~/.claude.json')
• test('returns default config when file does not exist')

describe('saveGlobalConfig')

• test('applies updater function to current config') — updater 修改被保存
• test('creates backup before writing') — 写入前备份
• test('prevents auth state loss') — wouldLoseAuthState 检查

describe('getCurrentProjectConfig')

• test('returns project config for current directory')
• test('returns default config when no project config exists')

describe('checkHasTrustDialogAccepted')

• test('returns true when trust is accepted in current directory')
• test('returns true when parent directory is trusted') — 父目录信任传递
• test('returns false when no trust accepted')
• test('caches positive results')

describe('isPathTrusted')

• test('returns true for trusted path')
• test('returns false for untrusted path')

describe('getOrCreateUserID')

• test('returns existing user ID from config')
• test('creates and persists new ID when none exists')
• test('returns consistent ID across calls')

---

src/utils/settings/settings.ts

describe('getSettingsFilePathForSource')

• test('returns ~/.claude/settings.json for userSettings') — 全局用户设置路径
• test('returns .claude/settings.json for projectSettings') — 项目设置路径
• test('returns .claude/settings.local.json for localSettings') — 本地设置路径

describe('parseSettingsFile')（需 Mock 文件读取）

• test('parses valid settings JSON') — 有效 JSON → { settings, errors: [] }
• test('returns errors for invalid fields') — 无效字段 → errors 非空
• test('returns empty settings for non-existent file')
• test('handles JSON with comments') — JSONC 格式支持

describe('getInitialSettings')

• test('merges settings from all sources') — user + project + local 合并
• test('later sources override earlier ones') — 优先级：policy > user > project > local

---

src/utils/settings/types.ts — Zod Schema 验证

describe('SettingsSchema validation')

• test('accepts valid minimal settings') — {} → 有效
• test('accepts permissions block') — { permissions: { allow: ['Bash(*)'] } } → 有效
• test('accepts model setting') — { model: 'sonnet' } → 有效
• test('accepts hooks configuration') — 有效的 hooks 对象被接受
• test('accepts env variables') — { env: { FOO: 'bar' } } → 有效
• test('rejects unknown top-level keys') — 未知字段被拒绝或忽略（取决于 schema 配置）
• test('rejects invalid permission mode') — { permissions: { defaultMode: 'invalid' } } → 错误
• test('rejects non-string model') — { model: 123 } → 错误
• test('accepts mcpServers configuration') — MCP server 配置有效
• test('accepts sandbox configuration')

---

src/utils/settings/validation.ts

describe('settings validation')

• test('validates permission rules format') — 'Bash(npm install)' 格式正确
• test('rejects malformed permission rules')
• test('validates hook configuration structure')
• test('provides helpful error messages') — 错误信息包含字段路径

---

Mock 需求

依赖	Mock 方式	说明
文件系统	临时目录 + mock	config 文件读写
lockfile	mock module	文件锁
getCwd	mock module	项目路径判断
findGitRoot	mock module	项目根目录
process.env	直接设置/恢复	CLAUDE_CODE_DISABLE_AUTOUPDATER 等

测试用临时文件结构

/tmp/claude-test-xxx/
├── .claude/
│   ├── settings.json        # projectSettings
│   └── settings.local.json  # localSettings
├── home/
│   └── .claude/
│       └── settings.json    # userSettings（mock HOME）
└── project/
    └── .git/

集成测试场景

describe('Config + Settings merge pipeline')

• test('user settings + project settings merge correctly') — 验证合并优先级
• test('deny rules from settings are reflected in tool permission context')
• test('trust dialog state persists across config reads')