websitedev/LINEAR-SYNC-GUIDE.md

Linear Sync Guide - Test Management

🎯 Cél: Linear-specifikus Test Management

Ez a dokumentum a Linear sync rendszerét írja le, amely csak a test management-re fókuszál.

---

🔄 Linear Sync Architektúra

Szinkronizációs Folyamat:

graph TD
    A[Test Execution] --> B[sync-test-management.js]
    B --> C[Linear API]
    C --> D[ZEE-47: Requirements]
    C --> E[ZEE-48: TC-001]
    C --> F[ZEE-49: TC-002]
    
    G[Manual Sync] --> B
    H[Test Reports] --> B
    I[Local Development] --> B

Mit szinkronizálunk Linear-ral:

• ✅ Requirements (ZEE-47: Contact Form Validation)
• ✅ Test Cases (ZEE-48: TC-001, ZEE-49: TC-002)
• ✅ Test Execution Results → Linear Comments
• ✅ Test Status Updates (Passed/Failed/Skipped)
• ✅ Traceability Matrix maintenance

---

🚀 Linear Sync Használata

1. Automatikus Sync (Test Execution után)

# Unit tesztek futtatása és sync
cd proto
npm run test:unit
npm run test:sync

# Integration tesztek futtatása és sync
npm run test:integration
npm run test:sync

# Összes teszt futtatása és sync
npm run test:all
npm run test:sync

2. Manuális Sync

# Csak sync futtatása (tesztek nélkül)
cd proto
npm run test:sync

# Vagy közvetlenül a script-tel
node ../scripts/sync-test-management.js

3. Custom Test Results Sync

# Saját test results fájllal
node scripts/sync-test-management.js --results-path custom-results.json

# Linear sync kihagyása
node scripts/sync-test-management.js --no-linear

---

📊 Linear Issue Mapping

Requirements (ZEE-47):

# REQ-001: Contact Form Validation Requirements

## Overview
A kapcsolati űrlap minden mezőjének megfelelő validációval kell rendelkeznie.

## Test Cases
- ZEE-48: Email Format Validation Test
- ZEE-49: Rate Limiting Integration Test

## Status
- Coverage: 100%
- Last Updated: [Auto-updated by sync]

Test Cases:

ZEE-48 (TC-001): Email Format Validation

# Test Case: Email Format Validation

**Requirement**: ZEE-47 (REQ-001)
**Type**: Unit Test
**Priority**: High

## Test Execution Results
- Status: ✅ PASSED
- Duration: 15ms
- Last Run: [Auto-updated]
- File: `src/app/api/contact/route.unit.test.ts`

## Automated Test Implementation
- File: `src/app/api/contact/route.unit.test.ts`
- Function: `TC-001: should detect invalid email formats`

ZEE-49 (TC-002): Rate Limiting Integration Test

# Test Case: Rate Limiting Integration Test

**Requirement**: ZEE-47 (REQ-001)
**Type**: Integration Test
**Priority**: Medium

## Test Execution Results
- Status: ✅ PASSED
- Duration: 250ms
- Last Run: [Auto-updated]
- File: `src/__tests__/integration.test.ts`

## Automated Test Implementation
- File: `src/__tests__/integration.test.ts`
- Function: `TC-002: should handle contact form rate limiting`

---

🔧 Linear Sync Konfiguráció

Environment Variables:

# Linear API Key (kötelező)
export LINEAR_API_KEY="your_linear_api_key_here"

# Opcionális beállítások
export LINEAR_TEAM_ID="zeener"  # Team ID (opcionális)
export LINEAR_WORKSPACE="zeener"  # Workspace (opcionális)

Sync Script Konfiguráció:

// scripts/sync-test-management.js
const CONFIG = {
  linearApiKey: process.env.LINEAR_API_KEY,
  teamId: process.env.LINEAR_TEAM_ID || 'zeener',
  workspace: process.env.LINEAR_WORKSPACE || 'zeener',
  
  // Test case mapping
  testCaseMapping: {
    'TC-001': 'ZEE-48', // Email Format Validation Test
    'TC-002': 'ZEE-49'  // Rate Limiting Integration Test
  }
};

---

📈 Sync Monitoring

Linear Dashboard:

• Requirements: ZEE-47
• Test Cases: ZEE-48, ZEE-49
• Team: Zeener Team

Sync Status Tracking:

# Sync script futtatása verbose módban
node scripts/sync-test-management.js --verbose

# Test results ellenőrzése
cat proto/test-management-report.json

# Linear issue status ellenőrzése
# (Linear web interface-en)

---

🛠️ Troubleshooting

Gyakori Problémák:

1. Linear API Key hiányzik

Error: LINEAR_API_KEY not set. Skipping Linear sync.

Megoldás:

export LINEAR_API_KEY="your_api_key"
# vagy
echo "export LINEAR_API_KEY=your_api_key" >> ~/.bashrc

2. Test results fájl nem található

Error: ENOENT: no such file or directory, open 'test-results.json'

Megoldás:

# Először futtasd a teszteket
npm run test:unit
# Majd a sync-et
npm run test:sync

3. Linear issue nem található

Warning: Linear issue ZEE-48 not found

Megoldás:

• Ellenőrizd, hogy a Linear issue létezik
• Ellenőrizd a test case mapping-et a script-ben
• Ellenőrizd a Linear API key permissions-ét

Debug Mód:

# Részletes logokkal
DEBUG=* node scripts/sync-test-management.js

# Vagy verbose output-tal
node scripts/sync-test-management.js --verbose

---

📋 Best Practices

1. Test Case Naming Convention:

// Teszt fájlokban használd ezt a formátumot:
it('TC-001: should validate email format', () => {
  // test implementation
});

it('TC-002: should handle rate limiting', () => {
  // test implementation
});

2. Regular Sync Schedule:

# Napi sync (cron job)
0 9 * * * cd /path/to/project && npm run test:sync

# Vagy manual sync fejlesztés közben
npm run test:unit && npm run test:sync

3. Linear Issue Maintenance:

• Requirements (ZEE-47) → Mindig frissítsd a coverage-t
• Test Cases (ZEE-48, ZEE-49) → Automatikus status update
• Comments → Automatikus test execution results

---

🔗 Kapcsolódó Dokumentumok

• Test Management Strategy
• Traceability Matrix
• GitHub CI/CD Guide
• Sync Status Analysis

---

Utolsó frissítés: 2025-09-05
Státusz: Linear sync szétválasztva GitHub-tól
Következő lépés: GitHub CI/CD dokumentáció létrehozása