integration-testing

Original：🇺🇸 English

Translated

Frontend-backend integration patterns, CORS configuration, API contract validation, and build hygiene for full-stack TypeScript applications. Use when integrating separate services or debugging cross-origin issues.

1installs

Sourcevineethsoma/agent-packages

Added on2026-02-22

NPX Install

npx skill4agent add vineethsoma/agent-packages integration-testing

SKILL.md Content

View Translation Comparison →

Integration Testing 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.

CORS Development Configuration

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

# backend/.env
CORS_ORIGIN=http://localhost:5173,http://localhost:5174,http://localhost:5175

# backend/.env.example (commit this)
CORS_ORIGIN=http://localhost:5173,http://localhost:5174,http://localhost:5175

API Contract Validation

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;
}

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

Build Artifact Hygiene

Critical: Compiled files must not shadow source files

TypeScript Project .gitignore

gitignore

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

# Exception: config files (use negation)
!vite.config.js
!playwright.config.js
!*.config.js

Pre-demo validation:

bash

# Check for stale .js in src/
find src/ -name "*.js" -type f | grep -v node_modules

# Should return empty or only intentional .js files

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"
  }
}