claude-code/docs/test-plans/07-cron.md

# Cron 调度测试计划

## 概述

Cron 模块提供 cron 表达式解析、下次运行时间计算和人类可读描述。全部为纯函数，无外部依赖，是最适合单元测试的模块之一。

## 被测文件

| 文件 | 关键导出 |
|------|----------|
| `src/utils/cron.ts` | `CronFields`, `parseCronExpression`, `computeNextCronRun`, `cronToHuman` |

---

## 测试用例

### describe('parseCronExpression')

#### 有效表达式

- test('parses wildcard fields') — `'* * * * *'` → 每个字段为完整范围
- test('parses specific values') — `'30 14 1 6 3'` → minute=[30], hour=[14], dom=[1], month=[6], dow=[3]
- test('parses step syntax') — `'*/5 * * * *'` → minute=[0,5,10,...,55]
- test('parses range syntax') — `'1-5 * * * *'` → minute=[1,2,3,4,5]
- test('parses range with step') — `'1-10/3 * * * *'` → minute=[1,4,7,10]
- test('parses comma-separated list') — `'1,15,30 * * * *'` → minute=[1,15,30]
- test('parses day-of-week 7 as Sunday alias') — `'0 0 * * 7'` → dow=[0]
- test('parses range with day-of-week 7') — `'0 0 * * 5-7'` → dow=[0,5,6]
- test('parses complex combined expression') — `'0,30 9-17 * * 1-5'` → 工作日 9-17 每半小时

#### 无效表达式

- test('returns null for wrong field count') — `'* * *'` → null
- test('returns null for out-of-range values') — `'60 * * * *'` → null（minute max=59）
- test('returns null for invalid step') — `'*/0 * * * *'` → null（step=0）
- test('returns null for reversed range') — `'10-5 * * * *'` → null（lo>hi）
- test('returns null for empty string') — `''` → null
- test('returns null for non-numeric tokens') — `'abc * * * *'` → null

#### 字段范围验证

- test('minute: 0-59')
- test('hour: 0-23')
- test('dayOfMonth: 1-31')
- test('month: 1-12')
- test('dayOfWeek: 0-6 (plus 7 alias)')

---

### describe('computeNextCronRun')

#### 基本匹配

- test('finds next minute') — from 14:30:45, cron `'31 14 * * *'` → 14:31:00 同天
- test('finds next hour') — from 14:30, cron `'0 15 * * *'` → 15:00 同天
- test('rolls to next day') — from 14:30, cron `'0 10 * * *'` → 10:00 次日
- test('rolls to next month') — from 1月31日, cron `'0 0 1 * *'` → 2月1日
- test('is strictly after from date') — from 恰好匹配时应返回下一次而非当前时间

#### DOM/DOW 语义

- test('OR semantics when both dom and dow constrained') — dom=15, dow=3 → 匹配 15 号 OR 周三
- test('only dom constrained uses dom') — dom=15, dow=* → 只匹配 15 号
- test('only dow constrained uses dow') — dom=*, dow=3 → 只匹配周三
- test('both wildcarded matches every day') — dom=*, dow=* → 每天

#### 边界情况

- test('handles month boundary') — 从 2 月 28 日寻找 2 月 29 日或 3 月 1 日
- test('returns null after 366-day search') — 不可能匹配的表达式返回 null（理论上不会发生）
- test('handles step across midnight') — `'0 0 * * *'` 从 23:59 → 次日 0:00

#### 每 N 分钟

- test('every 5 minutes from arbitrary time') — `'*/5 * * * *'` from 14:32 → 14:35
- test('every minute') — `'* * * * *'` from 14:32:45 → 14:33:00

---

### describe('cronToHuman')

#### 常见模式

- test('every N minutes') — `'*/5 * * * *'` → `'Every 5 minutes'`
- test('every minute') — `'*/1 * * * *'` → `'Every minute'`
- test('every hour at :00') — `'0 * * * *'` → `'Every hour'`
- test('every hour at :30') — `'30 * * * *'` → `'Every hour at :30'`
- test('every N hours') — `'0 */2 * * *'` → `'Every 2 hours'`
- test('daily at specific time') — `'30 9 * * *'` → `'Every day at 9:30 AM'`
- test('specific day of week') — `'0 9 * * 3'` → `'Every Wednesday at 9:00 AM'`
- test('weekdays') — `'0 9 * * 1-5'` → `'Weekdays at 9:00 AM'`

#### Fallback

- test('returns raw cron for complex patterns') — 非常见模式返回原始 cron 字符串
- test('returns raw cron for wrong field count') — `'* * *'` → 原样返回

#### UTC 模式

- test('UTC option formats time in local timezone') — `{ utc: true }` 时 UTC 时间转本地显示
- test('UTC midnight crossing adjusts day name') — UTC 时间跨天时本地星期名正确

---

## Mock 需求

**无需 Mock**。所有函数为纯函数，唯一的外部依赖是 `Date` 构造器和 `toLocaleTimeString`，可通过传入确定性的 `from` 参数控制。

## 注意事项

- `cronToHuman` 的时间格式化依赖系统 locale，测试中建议使用 `'en-US'` locale 或只验证部分输出
- `computeNextCronRun` 使用本地时区，DST 相关测试需注意运行环境