Test: assert MCP handler error message text (contract test)

[kiki830621]

Problem

ServerHandlerLogicTests.swift 目前的測試鎖定了「會拋 error」但沒有 assert specific error text：

XCTAssertThrowsError(try parseGetChatHistoryArgs([
    "chat_id": .int(100),
    "max_messages": .int(0),
]))

From verification of #7 by Codex:
「測試目前有鎖『會丟錯』，但沒有鎖使用者實際會看到的錯誤文字。如果錯誤訊息也算 MCP 契約的一部分，建議再補 1 到 2 個訊息比對。」

未來若有人把 errorResult("max_messages must be positive; got \(mm)") 改成模糊訊息（如 errorResult("invalid arg")），測試不會抓到——但 MCP caller 可能依賴訊息格式做錯誤處理。

Type

enhancement

Expected

補測試 assert (error as? HandlerArgError)?.description 或 (error as? DateParseError)?.description 的 prefix / substring，確保 error message 是契約的一部分。

Code Reference

• Tests/CheTelegramAllMCPTests/ServerHandlerLogicTests.swift:54-63（max_messages）
• Tests/CheTelegramAllMCPTests/ServerHandlerLogicTests.swift:106-114（invalid date）

Related: #7

---

Current Status

Phase: closed
Last updated: 2026-04-27 by idd-close

Key Decisions

• 用 exact equality match 而非 hasPrefix（為了鎖死契約字串）— 但 DA 反駁 brittleness，opened follow-up Test refactor: contract assertions use prefix-match instead of exact-equality #24 改 prefix-match
• 7 throws-based tests 升級（不加新 test，鎖文字）
• 6-AI verify: PASS

Scope Changes

(none — pure test contract tightening)

Blocking

(none)

Test counts

• 150 → 163 (Test: assert MCP handler error message text (contract test) #11 unchanged contribution; 9 new from MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8, 4 from Test: backward-compat numeric-string chat_id / from_message_id parsing #12, 0 new from Test: assert MCP handler error message text (contract test) #11)
• All 13 contract assertions pass
• Codex independent: 34 ServerHandlerLogicTests pass

Commits

• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11)
• f0203ac (related MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 fix): updated 1 contract assertion for revised .double behavior

Follow-up

• Test refactor: contract assertions use prefix-match instead of exact-equality #24 — Test contract use prefix-match instead of exact-equality (DA F6)

[kiki830621]

Diagnosis

Type

enhancement (test contract)

Analysis

現有 throws-based tests 鎖「會拋」但不 assert 具體錯誤訊息。錯誤訊息是 MCP caller 可依賴的 contract（caller 可能用 substring match 做錯誤分類），改成模糊訊息（如 errorResult("invalid arg")）不會被現有 tests 抓到。

Strategy

把 ~5 個關鍵 throws-based tests 從 XCTAssertThrowsError(...) 升級為 do-catch + XCTAssert(error.description.hasPrefix(...))。覆蓋：

• max_messages zero/negative
• max_messages over cap
• chat_id 缺失
• output_path 缺失（dump）
• invalid date format
• max_messages 非 integer (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 A1 引入的新訊息)

Complexity

Simple — 純 test 改動，無 source code 變更。

Risks

• 訊息文字一旦鎖在 test，未來改字串需要同步改 test → 這正是 contract test 的目的
• 用 hasPrefix 而非 == 留 implementation 彈性（caller 通常 prefix-match）

---

Implementation Plan

Phase 1: Convert XCTAssertThrowsError → do-catch + prefix assertions

• testMaxMessagesRejectsZeroOrNegative → assert prefix "max_messages must be positive"
• testMaxMessagesRejectsOverCap → assert prefix "max_messages exceeds 10_000 cap"
• testMissingChatIdThrows → assert prefix "chat_id is required"
• testDumpRequiresOutputPath → assert prefix "output_path is required"
• testInvalidDateFormatThrows → assert prefix "Date format invalid"
• (if MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 A1 commit landed first) testMaxMessagesAsDoubleRejected → assert prefix "max_messages must be an integer"

Phase 2: Verify

• swift test --skip E2ETests: all green
• CHANGELOG entry under same [0.5.3] Test section

Commit strategy

1 atomic commit (test-only, no source change).

Scope check

✅ 純 test addition，對應 issue Expected。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

Phase 1: Convert XCTAssertThrowsError → do-catch + exact message assertions

• testMaxMessagesRejectsZeroOrNegative → assert exact "max_messages must be positive; got 0" / "got -5"
• testMaxMessagesRejectsOverCap → assert exact "max_messages exceeds 10_000 cap; got 50000. Use since_date/until_date to narrow the range."
• testMissingChatIdThrows → assert exact "chat_id is required"（兩條 case）
• testDumpRequiresChatId → assert exact "chat_id is required"
• testDumpRequiresOutputPath → assert exact "output_path is required"
• testInvalidDateFormatThrows → assert exact "Date format invalid: expected YYYY-MM-DD, got \"...\"" 兩條 case（DateParseError）
• testMaxMessagesAsDoubleRejected → assert exact "max_messages must be an integer"（MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 A1 引入的新訊息）

Phase 2: Verify

• swift test --skip E2ETests: 156 → 160 (after Test: backward-compat numeric-string chat_id / from_message_id parsing #12 commit) all green
• CHANGELOG entry under [0.5.3] Test section（含 7 contract assertions）

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)

Changes

• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed

Files Changed (#11 scope)

 ServerHandlerLogicTests.swift  | +54 -10 (7 throwing-tests upgraded to assert exact text)
 CHANGELOG.md                   | (covered in 0.5.3 Test section)

Test counts

• Total: 160 tests (Test: assert MCP handler error message text (contract test) #11 doesn't add tests, only tightens existing assertions)
• All pass

Decision: exact match instead of hasPrefix

原 plan 寫 hasPrefix，實作改 XCTAssertEqual exact match — 更嚴格，鎖整條訊息（包含 "got 0" 數字、"Use since_date/until_date" 後綴）。hasPrefix 會放過尾段更動，違背 contract test 精神。

Scope Compliance

所有改動限於 ServerHandlerLogicTests.swift。0 source code 變更（純 test contract tightening）。

Next: verification pending

[kiki830621]

Verify: Batch 3 (#8 + #11 + #12 + subsumed #20)

Engine

Agent Team (5 Claude reviewers: requirements / logic / security / regression / devils-advocate) + Codex (gpt-5.5 xhigh) = 6-AI review

要求覆蓋率

• MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 4/4 sub-requirements addressed (FULLY) — type enforcement + DateParsing→TelegramAllLib + CLI parity + --until end-of-day
• Test: assert MCP handler error message text (contract test) #11 1/1 (FULLY in named cases; PARTIALLY if literally "all throws-tests") — 7 contract assertions on key tests
• Test: backward-compat numeric-string chat_id / from_message_id parsing #12 3/3 sub-requirements addressed (FULLY) + 1 dump parity test
• max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed: .string + .double rejection now correctly distinguishes type-error vs cap-error after DA fix

Findings（合併去重，按 severity 排序）

#	Severity	Finding	Source	Action
1	—	Behavior 100% equivalent for legitimate .int callers; truth tables verified across 14 cases (logic) and 24 tests pass independently (codex)	team:logic + codex	PASS
2	—	Scope check passed: only 6 files touched, 21 existing DateParsingTests still green after internal → public move	team:regression + codex	PASS
3	—	Visibility expansion (DateParsing → public in TelegramAllLib) is benign — pure parse, no FS/network	team:security	PASS
4	—	validateMaxMessagesCap shared helper continues to be security-positive (single source of truth for cap policy)	team:security	PASS
5	HIGH	parseMaxMessages rejected .double(5000.0) as type-mismatched, but JSON spec allows whole-number doubles. MCP SDK already provides Int(value, strict: false) (Value.swift:320) which uses Int(exactly:) to coerce whole-number doubles correctly. DIY dual-path missed this. In-scope fix f0203ac — replaced 8-line custom logic with single SDK call.	team:devils-advocate	In-scope fix ✓
6	MEDIUM	CLI ValidationError("--since \(e.description)") produces grammatically broken "--since Date format invalid: ..." (reads like flag is named --since Date). In-scope fix 2a05f83 — restored old phrasing "--since must be YYYY-MM-DD; got X" by extracting DateParseError.input directly.	team:devils-advocate	In-scope fix ✓
7	MEDIUM	testChatIdAsStringInvalidThrows asserts "chat_id is required" for .string("not-a-number"), but the field IS provided (just type-mismatched). Inconsistent with max_messages's strict "must be an integer". UX bug.	team:devils-advocate	Follow-up
8	MEDIUM	parseDumpChatToMarkdownArgs default 5000 no longer goes through validateMaxMessagesCap (only when key absent). Currently safe (5000 < 10_000) but if cap policy changes to 1000, default would silently bypass.	team:devils-advocate + logic LOW informational	Follow-up
9	MEDIUM	Exact-match contract tests (#11) lock cap value 10_000 and suggestion text. Cap policy change requires synchronized N-test update. Plan said hasPrefix; implementation chose exact.	team:devils-advocate	Follow-up
10	MEDIUM	Server.swift other numeric option args (limit ?? 50/20/200 at lines 374, 387, 446, 454) still have same silent-fallback pattern that #8 A1 fixed for max_messages. Only half-fixed.	team:devils-advocate	Follow-up
11	LOW	Phase 1 commit a918b11 is "dirty checkpoint" (parseMaxMessages exists but DateParsing still in MCPCore, CLI still inline). Repeat of #13 a834e88 anti-pattern. Third occurrence now.	team:devils-advocate	Won't fix (already past bisect window; future batches should squash phases)
12	LOW	#20 subsume is "ahistorical revisionism" — #8 original scope didn't include .double; expanded after DA finding.	team:devils-advocate	Won't fix (commit message + closing comment of #20 leave full audit trail)
13	LOW	CHANGELOG 0.5.3 mixes 4 issues (#8/#11/#12/#20) in one minor version. Users can't cherry-pick individual fixes.	team:devils-advocate	Won't fix (release cadence preference; can split future)
14	LOW	ServerHandlerLogicTests.swift now 426 lines (CLAUDE.md "200-400 typical"). Trajectory: #7 ~170, #13 ~290, #8/#11/#12 ~430. Approaching 500.	team:devils-advocate	Follow-up
15	LOW	testTarget doesn't explicitly depend on TelegramAllLib in Package.swift (works via transitive); CLI's parseCLIDate wrapper has no direct CLI integration test (relies on underlying 21 DateParsingTests)	team:regression	Won't fix (transitive deps + thin wrapper coverage adequate)

Devil's Advocate 反駁有效率

DA 反駁 4 reviewer + Codex 的「全 PASS」判定，找出 2 個 HIGH (F1+F2 = #5) + 4 MEDIUM + 2 LOW–MEDIUM + 3 LOW。

• 2 個 in-scope fix 已修（日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5/max_messages 邊界防護: 加硬上限 + 0/負數處理 #6，commits f0203ac + 2a05f83）
• 4 個 follow-up（MCP 層補 handler 行為 unit test（get_chat_history） #7/MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/改善 stderr log 格式: ASCII 箭號 + DateParseError internal visibility #9/Input hardening: DateParseError input truncate + since/until range sanity check #10 + Test: handler glue integration (errorResult conversion + tdlib wiring) #14）
• 3 個 won't fix（Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12/Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 + Test hardening: int64 helper DRY + boundary + TZ assertions #15，理由透明）

集體盲點被精準抓到：4 reviewer + Codex 都默認「strict reject .double 是 fix bug」，沒人翻 SDK 找 lenient API。Codex 雖驗證 5000 decode 成 .int(5000)，但漏了「caller 主動傳 5000.0」這條 cross-language ABI 路徑。

Codex 獨立貢獻

• 跑 swift test --filter ServerHandlerLogicTests (34 tests pass) + --filter DateParsingTests (14 tests pass) 自驗
• 直接讀 swift-sdk Value.swift Codable decode order，確認 JSON 5000 decode 成 .int(5000)（不是 .double(5000.0)）
• 點出 Test: assert MCP handler error message text (contract test) #11 嚴格解讀為 PARTIALLY（dump 的 throws tests 沒升級到 exact match — 可作為 Test: assert MCP handler error message text (contract test) #11 follow-up）

Scope Check

PASS — 改動限於 6 檔案（HandlerArgs / DateParsing / Server / TelegramAllCLI / 2 tests / CHANGELOG），全部追溯 #8/#11/#12/#20。F1+F2 + F3 in-scope fix 不擴大 scope，反而糾正原始實作的 over-correction。

Tests

• 150 → 163 tests pass, 0 failures
• Codex 獨立驗證 swift test 通過（34 + 14 = 48 隔離 filter tests）

Commits

• a918b11 fix: enforce max_messages type, reject string/double silent fallback (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8, max_messages silently falls back to default for .string/.double values (cap bypass) #20)
• b7e7899 fix: CLI date parity with MCP — share parseISODate/parseUntilDate (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8)
• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11)
• 2219206 test: lock backward-compat numeric-string chat_id/from_message_id (Test: backward-compat numeric-string chat_id / from_message_id parsing #12)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed
• f0203ac fix: accept whole-number .double via MCP SDK Int(value, strict:false) (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F1+F2)
• 2a05f83 fix: CLI date error message reuses old phrasing (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F3)

判決

PASS — 無 blocking findings 留存；2 個 HIGH/MEDIUM in-scope 已修復（f0203ac + 2a05f83）；5 個 valid follow-ups（#7/#8/#9/#10/#14）待 user triage；3 個 informational won't-fix 理由透明。

[kiki830621]

Closing Summary

Problem

#7 verify 階段 Codex 點出：ServerHandlerLogicTests.swift 的 throws-based tests 鎖了「會拋 error」但沒 assert 具體錯誤訊息。MCP caller 可能用 substring match 做錯誤分類（例如 "max_messages must be positive" 前綴）— 但若有人把訊息改成模糊 "invalid arg"，現有 tests 不會抓到，caller 端會 silently break。

Root Cause

• IDD 早期 contract test 主要鎖「行為形狀」（throws / 不 throws / parsed value），訊息文字是隱含 contract 但未被斷言
• MCP caller 沒有結構化 error type（HandlerArgError 是 internal struct），只能透過 stringified description 做 routing → message text 就是 API contract，但 test 沒鎖

Solution

把 7 個 throws-based test 從 XCTAssertThrowsError(...) 升級為 XCTAssertThrowsError { error in ... } 配 trailing closure 做 message assertion：

XCTAssertThrowsError(...) { error in
    XCTAssertEqual(
        (error as? HandlerArgError)?.description,
        "max_messages must be positive; got 0"
    )
}

採 exact equality match 而非 hasPrefix（鎖死整條訊息含尾段 suggestion "Use since_date/until_date to narrow the range."）。覆蓋：

• max_messages zero/negative + over-cap
• chat_id 缺失（兩條 case）
• output_path 缺失（dump）
• invalid date format（兩條 case，DateParseError）
• max_messages 非 integer（MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 A1 引入的新訊息）

13 條 contract assertions in test file（(error as? HandlerArgError)?.description + (error as? DateParseError)?.description 各算）。

Verification

Engine：5 Claude reviewers + Codex = 6-AI。

維度	Result
1/1 req（exact text assertions on key tests）	FULLY for named cases
7 contract assertions	byte-level pass
Test count	不變（只升級既有 tests，不加新 test）
Cross-validation by Codex	swift test --filter ServerHandlerLogicTests 34 pass

Codex 點出 strict 解讀為 PARTIALLY：dump 版的 throws tests（dump max_messages、dump invalid date）沒升級到 exact match。為此開 follow-up #24 修 brittleness（同時兼顧 dump 升級）。

DA 反駁 exact-match brittleness（MEDIUM）：鎖 cap 數值 10_000 與 suggestion 文字會讓 cap policy 變更時連動 N 個 test fail。Plan 寫 hasPrefix，實作改 exact 是 over-shoot。Follow-up #24 處理。

Changes

• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11)
• f0203ac (related MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 fix): updated 1 contract assertion from "must be an integer" type-error path to "exceeds 10_000 cap" cap-error path（whole-number .double 修法後 .double(20000.0) 走 cap 不走 type）
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed

Follow-up

• Test refactor: contract assertions use prefix-match instead of exact-equality #24 — Test contract use prefix-match instead of exact-equality（DA F6，addresses brittleness）