wangziqi
b6d398b102
Phase 1: 共用类型定义 - apps/server/src/common/import-result.types.ts — ImportRowError + ImportResult<T> - apps/admin/src/types/import.ts — 前端对应类型 + ImportDisplayConfig Phase 2: 后端增强 - students.service.ts — batchImport/matchImport 改为 ImportResult 格式 · 每行跳过时收集 ImportRowError（code + reason） · reason 支持 markdown 标记（**字段名** / `值`） - archive.service.ts — batchImportArchive 统一用 ImportResult 格式 · 各 Sheet 错误使用标准 error code - archive.controller.ts — 日志使用新的 success 字段 Phase 3: 前端基础 - 安装 react-markdown - ImportResultModal 组件（共用导入结果弹窗） · Statistic 成功统计 + Table 错误明细 · 原因列支持 react-markdown 渲染（粗体字段名、等宽代码值） · 错误类型用 Tag 颜色区分 - api/index.ts — 403 错误从 console.warn 改为 message.warning 用户可见 Phase 4: 前端集成 - Students/index.tsx — 替换硬编码导入结果弹窗 · 删除'后端只返回统计汇总'注释和跳过原因 hardcode · 新格式自动使用 ImportResultModal，旧格式兼容 - StudentProfileContent/index.tsx — 替换内联导入 Modal 为 ImportResultModal
116 lines
3.4 KiB
Markdown
116 lines
3.4 KiB
Markdown
# Condition-Based Waiting
|
|
|
|
## Overview
|
|
|
|
Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
|
|
|
|
**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
|
|
|
|
## When to Use
|
|
|
|
```dot
|
|
digraph when_to_use {
|
|
"Test uses setTimeout/sleep?" [shape=diamond];
|
|
"Testing timing behavior?" [shape=diamond];
|
|
"Document WHY timeout needed" [shape=box];
|
|
"Use condition-based waiting" [shape=box];
|
|
|
|
"Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
|
|
"Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
|
|
"Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
|
|
}
|
|
```
|
|
|
|
**Use when:**
|
|
- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
|
|
- Tests are flaky (pass sometimes, fail under load)
|
|
- Tests timeout when run in parallel
|
|
- Waiting for async operations to complete
|
|
|
|
**Don't use when:**
|
|
- Testing actual timing behavior (debounce, throttle intervals)
|
|
- Always document WHY if using arbitrary timeout
|
|
|
|
## Core Pattern
|
|
|
|
```typescript
|
|
// ❌ BEFORE: Guessing at timing
|
|
await new Promise(r => setTimeout(r, 50));
|
|
const result = getResult();
|
|
expect(result).toBeDefined();
|
|
|
|
// ✅ AFTER: Waiting for condition
|
|
await waitFor(() => getResult() !== undefined);
|
|
const result = getResult();
|
|
expect(result).toBeDefined();
|
|
```
|
|
|
|
## Quick Patterns
|
|
|
|
| Scenario | Pattern |
|
|
|----------|---------|
|
|
| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
|
|
| Wait for state | `waitFor(() => machine.state === 'ready')` |
|
|
| Wait for count | `waitFor(() => items.length >= 5)` |
|
|
| Wait for file | `waitFor(() => fs.existsSync(path))` |
|
|
| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
|
|
|
|
## Implementation
|
|
|
|
Generic polling function:
|
|
```typescript
|
|
async function waitFor<T>(
|
|
condition: () => T | undefined | null | false,
|
|
description: string,
|
|
timeoutMs = 5000
|
|
): Promise<T> {
|
|
const startTime = Date.now();
|
|
|
|
while (true) {
|
|
const result = condition();
|
|
if (result) return result;
|
|
|
|
if (Date.now() - startTime > timeoutMs) {
|
|
throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
|
|
}
|
|
|
|
await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
|
|
}
|
|
}
|
|
```
|
|
|
|
See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
|
|
|
|
## Common Mistakes
|
|
|
|
**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
|
|
**✅ Fix:** Poll every 10ms
|
|
|
|
**❌ No timeout:** Loop forever if condition never met
|
|
**✅ Fix:** Always include timeout with clear error
|
|
|
|
**❌ Stale data:** Cache state before loop
|
|
**✅ Fix:** Call getter inside loop for fresh data
|
|
|
|
## When Arbitrary Timeout IS Correct
|
|
|
|
```typescript
|
|
// Tool ticks every 100ms - need 2 ticks to verify partial output
|
|
await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
|
|
await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
|
|
// 200ms = 2 ticks at 100ms intervals - documented and justified
|
|
```
|
|
|
|
**Requirements:**
|
|
1. First wait for triggering condition
|
|
2. Based on known timing (not guessing)
|
|
3. Comment explaining WHY
|
|
|
|
## Real-World Impact
|
|
|
|
From debugging session (2025-10-03):
|
|
- Fixed 15 flaky tests across 3 files
|
|
- Pass rate: 60% → 100%
|
|
- Execution time: 40% faster
|
|
- No more race conditions
|