integration-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integration Testing Skill

集成测试Skill

This skill captures critical learnings from US-001 (birdmate project) where 3 integration bugs appeared in demo despite 272 passing unit tests. Covers CORS configuration, API contract validation, and build artifact hygiene.

本Skill总结了US-001（birdmate项目）中的关键经验：尽管有272个通过的单元测试，但演示中仍出现了3个集成bug。内容涵盖CORS配置、API契约验证及构建产物规范。

CORS Development Configuration

CORS开发配置

Critical Pattern: Development CORS must accommodate dynamic port assignment

typescript

// ❌ WRONG - Single hardcoded origin
const CORS_ORIGIN = 'http://localhost:5173';

// ✅ CORRECT - Support port range
const CORS_ORIGINS = (process.env.CORS_ORIGIN || 
  'http://localhost:5173,http://localhost:5174,http://localhost:5175'
).split(',').map(s => s.trim());

app.use(cors({ origin: CORS_ORIGINS, credentials: true }));

Why: Vite/dev servers auto-increment ports when default is occupied

Configuration Template:

bash

undefined

关键模式：开发环境下的CORS必须支持动态端口分配

typescript

// ❌ 错误 - 单一硬编码源
const CORS_ORIGIN = 'http://localhost:5173';

// ✅ 正确 - 支持端口范围
const CORS_ORIGINS = (process.env.CORS_ORIGIN || 
  'http://localhost:5173,http://localhost:5174,http://localhost:5175'
).split(',').map(s => s.trim());

app.use(cors({ origin: CORS_ORIGINS, credentials: true }));

原因：当默认端口被占用时，Vite/开发服务器会自动递增端口

配置模板:

bash

undefined

backend/.env

CORS_ORIGIN=http://localhost:5173,http://localhost:5174,http://localhost:5175

backend/.env.example (commit this)

backend/.env.example（提交此文件）

CORS_ORIGIN=http://localhost:5173,http://localhost:5174,http://localhost:5175

undefined

CORS_ORIGIN=http://localhost:5173,http://localhost:5174,http://localhost:5175

undefined

API Contract Validation

API契约验证

Critical: Types at integration boundary must match wire format

关键要点：集成边界的类型必须与传输格式匹配

Anti-Pattern: Over-abstraction

反模式：过度抽象

typescript

// Shared type (ideal design, not actual API)
interface SearchResult {
  bird: Bird;  // ❌ Nested structure
  score: number;
}

typescript

// 共享类型（理想设计，非实际API）
interface SearchResult {
  bird: Bird;  // ❌ 嵌套结构
  score: number;
}

Correct Pattern: Wire-format types

正确模式：传输格式类型

typescript

// API response types (match actual backend)
interface ApiSearchResult {
  id: string;         // ✅ Flat structure
  commonName: string;
  score: number;
}

// Transform at boundary
function transformResults(apiResults: ApiSearchResult[]): AppResult[] {
  return apiResults.map(api => ({
    bird: { id: api.id, commonName: api.commonName },
    score: api.score
  }));
}

Validation Checklist:

Test API endpoint with curl, inspect actual JSON
Create
```
Api*
```
types matching exact response structure
Transform to app types at integration boundary only
Never assume shared types match wire format

typescript

// API响应类型（与实际后端匹配）
interface ApiSearchResult {
  id: string;         // ✅ 扁平结构
  commonName: string;
  score: number;
}

// 在边界处转换
function transformResults(apiResults: ApiSearchResult[]): AppResult[] {
  return apiResults.map(api => ({
    bird: { id: api.id, commonName: api.commonName },
    score: api.score
  }));
}

验证检查清单:

使用curl测试API端点，检查实际JSON结构
创建与响应结构完全匹配的
```
Api*
```
类型
仅在集成边界处转换为应用类型
切勿假设共享类型与传输格式一致

Build Artifact Hygiene

构建产物规范

Critical: Compiled files must not shadow source files

关键要点：编译文件不得覆盖源文件

TypeScript Project .gitignore

TypeScript项目.gitignore

gitignore

undefined

gitignore

undefined

Compiled outputs

编译输出

dist/ build/ *.js # ⚠️ CRITICAL in src/ directories *.js.map *.jsx *.jsx.map

dist/ build/ *.js # ⚠️ 在src/目录中至关重要 *.js.map *.jsx *.jsx.map

Exception: config files (use negation)

例外：配置文件（使用否定规则）

!vite.config.js !playwright.config.js !*.config.js


**Pre-demo validation**:
```bash

!vite.config.js !playwright.config.js !*.config.js


**预演示验证**:
```bash

Check for stale .js in src/

检查src/中的旧.js文件

find src/ -name "*.js" -type f | grep -v node_modules

Should return empty or only intentional .js files

应返回空或仅包含有意保留的.js文件


**Package.json clean scripts**:
```json
{
  "scripts": {
    "clean": "find src/ -name '*.js' -o -name '*.jsx' | xargs rm -f",
    "prebuild": "npm run clean",
    "predev": "npm run clean"
  }
}


**Package.json清理脚本**:
```json
{
  "scripts": {
    "clean": "find src/ -name '*.js' -o -name '*.jsx' | xargs rm -f",
    "prebuild": "npm run clean",
    "predev": "npm run clean"
  }
}