168 lines
4.1 KiB
Markdown
168 lines
4.1 KiB
Markdown
# Contract Testing Quick Start Guide
|
||
|
||
## 🚀 Quick Setup
|
||
|
||
### 1. Run the Full Contract Test Suite
|
||
```bash
|
||
npm run test:contracts
|
||
```
|
||
|
||
This single command will:
|
||
- ✅ Validate API contracts
|
||
- ✅ Generate OpenAPI spec
|
||
- ✅ Generate TypeScript types
|
||
- ✅ Check for breaking changes
|
||
- ✅ Verify website type compatibility
|
||
|
||
### 2. Individual Commands
|
||
|
||
```bash
|
||
# Validate API contracts only
|
||
npm run test:api:contracts
|
||
|
||
# Generate types (after making DTO changes)
|
||
npm run api:sync-types
|
||
|
||
# Check compatibility (detect breaking changes)
|
||
npm run test:contract:compatibility
|
||
|
||
# Verify website can consume types
|
||
npm run website:type-check
|
||
```
|
||
|
||
## 📁 What Gets Created
|
||
|
||
### Generated Types
|
||
- **Location**: `apps/website/lib/types/generated/`
|
||
- **Files**: One `.ts` file per DTO (e.g., `RaceDTO.ts`, `DriverDTO.ts`)
|
||
- **Usage**: Import directly in website code
|
||
|
||
### Test Files
|
||
- **API Tests**: `apps/api/src/shared/testing/contractValidation.test.ts`
|
||
- **Website Tests**: `apps/website/lib/types/contractConsumption.test.ts`
|
||
|
||
### CI/CD
|
||
- **Workflow**: `.github/workflows/contract-testing.yml`
|
||
- **Triggers**: Pull requests and main branch pushes
|
||
|
||
## 🎯 Common Workflows
|
||
|
||
### Making API Changes
|
||
|
||
1. **Update DTO in API**:
|
||
```typescript
|
||
// apps/api/src/domain/race/dtos/RaceDTO.ts
|
||
export class RaceDTO {
|
||
@ApiProperty()
|
||
id: string;
|
||
|
||
@ApiProperty()
|
||
name: string;
|
||
|
||
@ApiProperty({ required: false })
|
||
description?: string; // New optional field
|
||
}
|
||
```
|
||
|
||
2. **Run contract tests**:
|
||
```bash
|
||
npm run test:contracts
|
||
```
|
||
|
||
3. **If tests pass**, commit your changes. The CI will regenerate types automatically.
|
||
|
||
### Updating Website Code
|
||
|
||
1. **Import generated types**:
|
||
```typescript
|
||
import type { RaceDTO } from '@/lib/types/generated/RaceDTO';
|
||
|
||
function RaceComponent({ race }: { race: RaceDTO }) {
|
||
return <div>{race.name}</div>;
|
||
}
|
||
```
|
||
|
||
2. **TypeScript will catch errors** if contracts change.
|
||
|
||
### Detecting Breaking Changes
|
||
|
||
```bash
|
||
# This will show you exactly what changed
|
||
npm run test:contract:compatibility
|
||
```
|
||
|
||
Output example:
|
||
```
|
||
🚨 BREAKING CHANGES DETECTED:
|
||
• RaceDTO.status: Property status was removed (BREAKING)
|
||
|
||
❌ REMOVED:
|
||
• OldDTO: DTO OldDTO was removed
|
||
|
||
➕ ADDED:
|
||
• NewDTO: New DTO NewDTO was added
|
||
```
|
||
|
||
## 🔧 Troubleshooting
|
||
|
||
### "Cannot find module" errors
|
||
```bash
|
||
# Regenerate types
|
||
npm run api:sync-types
|
||
```
|
||
|
||
### Type generation fails
|
||
1. Check DTOs have `@ApiProperty` decorators
|
||
2. Verify OpenAPI spec is valid: `cat apps/api/openapi.json`
|
||
3. Run individual steps:
|
||
```bash
|
||
npm run api:generate-spec
|
||
npm run api:generate-types
|
||
```
|
||
|
||
### CI fails on breaking changes
|
||
- Review what changed
|
||
- Update website code to handle new types
|
||
- Or revert the breaking change if unintended
|
||
|
||
## 📋 Checklist Before Committing
|
||
|
||
- [ ] Run `npm run test:contracts` locally
|
||
- [ ] All tests pass
|
||
- [ ] No breaking changes (or they're intentional)
|
||
- [ ] Website code updated to handle new types
|
||
- [ ] Generated types are committed (if needed)
|
||
|
||
## 🎓 Key Concepts
|
||
|
||
### What is a "Contract"?
|
||
A contract is the agreement between API and website about what data looks like:
|
||
- DTO definitions
|
||
- Property types
|
||
- Required vs optional fields
|
||
|
||
### What are "Breaking Changes"?
|
||
Changes that would break the website:
|
||
- Removing required fields
|
||
- Changing field types
|
||
- Adding required fields to existing DTOs
|
||
|
||
### Why Generate Types?
|
||
- **Type Safety**: Catch errors at compile time
|
||
- **Auto-completion**: Better IDE experience
|
||
- **Documentation**: Types serve as living documentation
|
||
- **Consistency**: Single source of truth
|
||
|
||
## 🚨 Important Notes
|
||
|
||
1. **Never manually edit generated files** - they're auto-generated
|
||
2. **Always run tests before committing** - prevents breaking changes
|
||
3. **The CI will regenerate types** - but local verification is faster
|
||
4. **Breaking changes need review** - consider versioning strategy
|
||
|
||
## 📚 More Resources
|
||
|
||
- Full documentation: `docs/CONTRACT_TESTING.md`
|
||
- API examples: `apps/api/src/shared/testing/contractValidation.test.ts`
|
||
- Website examples: `apps/website/lib/types/contractConsumption.test.ts`
|
||
- CI/CD workflow: `.github/workflows/contract-testing.yml` |