docs(tests): add comprehensive test plan for matching integration tests
This commit is contained in:
Radosław Gierwiało
377
backend/src/__tests__/matching-scenarios.md
Normal file
377
backend/src/__tests__/matching-scenarios.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# Matching Algorithm - Integration Test Scenarios
|
||||
|
||||
High-level test plan for `runMatching()` integration tests.
|
||||
|
||||
## Test Organization
|
||||
|
||||
- **Unit tests** (`matching.test.js`): Helper functions (getTimeSlot, buffers, collision detection)
|
||||
- **Integration tests** (to implement): End-to-end scenarios for runMatching()
|
||||
|
||||
## Test Scenarios
|
||||
|
||||
### 1. Podstawowe zachowanie matchingu
|
||||
|
||||
#### TC1: Jeden tancerz, jeden wolny recorder → prosty happy path
|
||||
|
||||
**Setup:**
|
||||
- Event: 1 dancer (Basic), 1 recorder (Basic)
|
||||
- Heaty:
|
||||
- dancer tańczy w 1 heacie (np. Novice H10)
|
||||
- recorder nie tańczy w żadnym heacie
|
||||
- Brak kolizji, brak slot mapy (divisionSlotMap = null)
|
||||
|
||||
**Oczekiwania:**
|
||||
- `runMatching` zwraca 1 sugestię:
|
||||
- `heatId` = heat dancera
|
||||
- `recorderId` = recorder.userId
|
||||
- `status` = PENDING
|
||||
- Brak wpisów NOT_FOUND
|
||||
|
||||
---
|
||||
|
||||
#### TC2: Brak recorderów → NOT_FOUND
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer (Basic)
|
||||
- `potentialRecorders = []` (wszyscy mają recorderOptOut = true albo nikt inny nie jest na evencie)
|
||||
- Dancer ma 1 heat
|
||||
|
||||
**Oczekiwania:**
|
||||
- Sugestia:
|
||||
- `recorderId = null`
|
||||
- `status = NOT_FOUND`
|
||||
|
||||
---
|
||||
|
||||
#### TC3: Wszyscy recorderzy to self → NOT_FOUND
|
||||
|
||||
**Setup:**
|
||||
- Event ma tylko jednego uczestnika:
|
||||
- ma competitorNumber (czyli jest dancerem)
|
||||
- nie ma opt-out (czyli teoretycznie mógłby być recorderem)
|
||||
- Ma 1 heat
|
||||
|
||||
**Oczekiwania:**
|
||||
- `runMatching` nie przydzieli go samego do nagrywania
|
||||
- Sugestia:
|
||||
- `recorderId = null`
|
||||
- `status = NOT_FOUND`
|
||||
|
||||
---
|
||||
|
||||
### 2. Kolizje + buffery + sloty
|
||||
|
||||
#### TC4: Recorder tańczy w tym samym heacie → nie może nagrywać
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer (Basic), 1 recorder (Basic)
|
||||
- Obaj mają ten sam heat: division=1, compType=1, heatNumber=10
|
||||
- divisionSlotMap puste
|
||||
|
||||
**Oczekiwania:**
|
||||
- Recorder jest w `recorderBusySlots` w tym slocie
|
||||
- Kandydaci dla tego heatu = [] → NOT_FOUND
|
||||
|
||||
---
|
||||
|
||||
#### TC5: Recorder w buforze PRZED tańcem → nie może nagrywać
|
||||
|
||||
**Setup:**
|
||||
- HEAT_BUFFER_BEFORE = 1
|
||||
- Dancer: heat 9
|
||||
- Recorder: heat 10
|
||||
- Ten sam divisionId i competitionTypeId, brak slot mapy
|
||||
|
||||
**Oczekiwania:**
|
||||
- `getPreDanceBufferSlots` dla heat 10 blokuje heat 9
|
||||
- `recorderBusySlots` zawiera heat 9
|
||||
- `runMatching` nie wybierze recordera dla heatu 9 → NOT_FOUND
|
||||
|
||||
---
|
||||
|
||||
#### TC6: Recorder w buforze PO tańcu → nie może nagrywać
|
||||
|
||||
**Setup:**
|
||||
- HEAT_BUFFER_AFTER = 1
|
||||
- Dancer: heat 11
|
||||
- Recorder: heat 10
|
||||
- Ten sam division / compType, brak slot mapy
|
||||
|
||||
**Oczekiwania:**
|
||||
- `getPostDanceBufferSlots` dla heat 10 blokuje heat 11
|
||||
- `recorderBusySlots` zawiera heat 11
|
||||
- NOT_FOUND dla heatu 11
|
||||
|
||||
---
|
||||
|
||||
#### TC7: Brak kolizji gdy heat jest poza buforem
|
||||
|
||||
**Setup:**
|
||||
- HEAT_BUFFER_BEFORE = HEAT_BUFFER_AFTER = 1
|
||||
- Dancer: heat 12
|
||||
- Recorder: heat 10
|
||||
- Ten sam division / compType
|
||||
|
||||
**Oczekiwania:**
|
||||
- Busy slots recordera: 9, 10, 11
|
||||
- Heat 12 nie jest busy → recorder może nagrywać
|
||||
- `runMatching` przypisuje recordera do heatu 12
|
||||
|
||||
---
|
||||
|
||||
#### TC8: Kolizja pomiędzy dywizjami w tym samym slocie (divisionSlotMap)
|
||||
|
||||
**Setup:**
|
||||
- divisionSlotMap:
|
||||
- Novice (1) → slot 1
|
||||
- Intermediate (2) → slot 1 (równolegle)
|
||||
- Dancer tańczy: division 1, compType 1, heatNumber 1
|
||||
- Recorder tańczy: division 2, compType 1, heatNumber 1
|
||||
- Czyli: inna division, ten sam slot i heatNumber
|
||||
|
||||
**Oczekiwania:**
|
||||
- `getTimeSlot` dla obu → ten sam string `slot1-1-1`
|
||||
- Recorder busy w tym slocie → nie może być recorderem dla tego heatu
|
||||
- NOT_FOUND (jeśli nie ma innych recorderów)
|
||||
|
||||
---
|
||||
|
||||
#### TC9: Brak kolizji gdy dywizje w różnych slotach
|
||||
|
||||
**Setup:**
|
||||
- divisionSlotMap:
|
||||
- Novice (1) → slot 1
|
||||
- Advanced (3) → slot 2
|
||||
- Dancer: division 1, compType 1, heatNumber 1
|
||||
- Recorder: division 3, compType 1, heatNumber 1
|
||||
|
||||
**Oczekiwania:**
|
||||
- Dwa różne sloty → różne `getTimeSlot`
|
||||
- Recorder nie jest busy dla slota dancera
|
||||
- Recorder zostaje przypisany
|
||||
|
||||
---
|
||||
|
||||
### 3. Limity przydziałów + zajętość przez nagrywanie
|
||||
|
||||
#### TC10: MAX_RECORDINGS_PER_PERSON jest respektowane
|
||||
|
||||
**Setup:**
|
||||
- MAX_RECORDINGS_PER_PERSON = 3
|
||||
- 1 recorder, wielu dancerów
|
||||
- Recorder nie tańczy w żadnych heatach
|
||||
- Dancerzy: 4 różne osoby, każdy ma inny heat (bez kolizji w czasie)
|
||||
|
||||
**Oczekiwania:**
|
||||
- `runMatching`:
|
||||
- Przydzieli recordera do pierwszych 3 heatów (deterministycznie, wg kolejności, location itp.)
|
||||
- 4. heat dostanie NOT_FOUND (bo recorder ma już 3 nagrania i zostanie odfiltrowany)
|
||||
|
||||
---
|
||||
|
||||
#### TC11: Zajętość przez nagrywanie blokuje kolejne przydziały
|
||||
|
||||
**Setup:**
|
||||
- 1 recorder, 2 dancerów
|
||||
- Sloty:
|
||||
- Dancer A: heatNumber 10
|
||||
- Dancer B: heatNumber 10 (ten sam slot i division/compType)
|
||||
- Recorder NIE tańczy w tym czasie
|
||||
|
||||
**Oczekiwania:**
|
||||
- Przy pierwszym dancerze:
|
||||
- recorder jest wolny → zostaje przypisany
|
||||
- heatSlot (slot dla H10) zostaje dopisany do `recorderBusySlots` jako "nagrywa"
|
||||
- Przy drugim dancerze:
|
||||
- busySlots recordera zawiera slot H10 → odpada jako kandydat
|
||||
- jeśli brak innych recorderów → NOT_FOUND
|
||||
|
||||
**Uwaga:** To weryfikuje, że naprawiłeś bug "recorder nagrywa 2 osoby w tym samym czasie"
|
||||
|
||||
---
|
||||
|
||||
### 4. Fairness (recordingsDone/recordingsReceived)
|
||||
|
||||
**Mock stats example:**
|
||||
```javascript
|
||||
statsByUserId.set(recorder1.userId, { recordingsDone: 0, recordingsReceived: 0 });
|
||||
statsByUserId.set(recorder2.userId, { recordingsDone: 10, recordingsReceived: 0 });
|
||||
```
|
||||
|
||||
#### TC12: Większy fairnessDebt → częściej wybierany jako recorder
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer, 2 recorderów (wszyscy Basic, ta sama lokalizacja, brak kolizji, currentAssignments=0)
|
||||
- Stats:
|
||||
- Recorder A: done=0, received=10 → fairnessDebt=+10
|
||||
- Recorder B: done=0, received=0 → fairnessDebt=0
|
||||
|
||||
**Oczekiwania:**
|
||||
- Obaj są kandydatami
|
||||
- Sorting:
|
||||
- locationScore A == B
|
||||
- fairnessDebt A (10) > B (0)
|
||||
- `best.recorder.userId` = Recorder A
|
||||
|
||||
---
|
||||
|
||||
#### TC13: Fairness działa po locationScore
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer z Warszawy
|
||||
- Recorder A:
|
||||
- mieszka w Warszawie (locScore=3)
|
||||
- fairnessDebt = 0
|
||||
- Recorder B:
|
||||
- mieszka w innym kraju (locScore=1)
|
||||
- fairnessDebt = 100 (duży dług)
|
||||
- Brak kolizji, assignmentCount=0
|
||||
|
||||
**Oczekiwania:**
|
||||
- Najpierw location: A (3) > B (1)
|
||||
- B nie przebije A mimo giga fairnessDebt
|
||||
- Wybrany recorder = A
|
||||
|
||||
**Uwaga:** To potwierdza priorytet: lokalizacja > fairness > load balancing
|
||||
|
||||
---
|
||||
|
||||
### 5. Tiery: Basic / Supporter / Comfort
|
||||
|
||||
Zakładamy, że stats w testach startują od 0/0, więc "gołe" fairnessDebt=0 dla każdego.
|
||||
|
||||
#### TC14: Basic vs Supporter vs Comfort – kto pierwszy w kolejności?
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer, 3 recorderów w tej samej lokalizacji, brak kolizji, same heat, currentAssignments=0
|
||||
- Tier:
|
||||
- Recorder Basic: tier=BASIC
|
||||
- Recorder Supporter: tier=SUPPORTER
|
||||
- Recorder Comfort: tier=COMFORT
|
||||
- Stats:
|
||||
- wszystkim ustaw recordingsDone = 0, recordingsReceived = 0
|
||||
- fairness przed karami = 0
|
||||
|
||||
**Oczekiwania:**
|
||||
- fairnessDebt po karach:
|
||||
- Basic: 0
|
||||
- Supporter: 0 - FAIRNESS_SUPPORTER_PENALTY
|
||||
- Comfort: 0 - FAIRNESS_COMFORT_PENALTY (najniżej)
|
||||
- Kolejność kandydatów po posortowaniu:
|
||||
1. Basic
|
||||
2. Supporter
|
||||
3. Comfort
|
||||
- `best.recorder` = Basic
|
||||
|
||||
---
|
||||
|
||||
#### TC15: Supporter vs Comfort – Basic odpada przez kolizję/limit
|
||||
|
||||
**Setup:**
|
||||
- Trzech recorderów jak wyżej
|
||||
- Basic ma kolizję czasową (slot busy) albo osiągnięty limit nagrań → nie trafia do candidates
|
||||
- Supporter i Comfort są wolni, ta sama lokalizacja, fairness startowe 0
|
||||
|
||||
**Oczekiwania:**
|
||||
- fairnessDebt:
|
||||
- Supporter: −FAIRNESS_SUPPORTER_PENALTY
|
||||
- Comfort: −FAIRNESS_COMFORT_PENALTY (bardziej ujemne)
|
||||
- `best.recorder` = Supporter
|
||||
- Comfort zostaje użyty tylko, jeśli Supporter też wypadnie
|
||||
|
||||
---
|
||||
|
||||
#### TC16: Comfort użyty tylko jako ostateczność
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer, 2 recorderów:
|
||||
- Recorder A: Basic, ale:
|
||||
- konflikt czasowy (busySlots zawiera heatSlot) albo ma MAX_RECORDINGS_PER_PERSON
|
||||
- Recorder B: Comfort, brak konfliktu/workload
|
||||
- Taka sama lokalizacja
|
||||
|
||||
**Oczekiwania:**
|
||||
- A nie trafi do candidates (kolizja lub limit)
|
||||
- jedyny kandydat to Comfort
|
||||
- `best.recorder` = Comfort
|
||||
|
||||
**Uwaga:** To pokazuje, że Comfort nie ma hard opt-out – może zostać użyty, gdy nie ma innej opcji
|
||||
|
||||
---
|
||||
|
||||
### 6. Edge-case'y / sanity
|
||||
|
||||
#### TC17: Dancer bez heatów → jest ignorowany
|
||||
|
||||
**Setup:**
|
||||
- Event:
|
||||
- Participant A ma competitorNumber, ale nie ma żadnych entry w eventUserHeat
|
||||
- 1 inny uczestnik jako recorder
|
||||
|
||||
**Oczekiwania:**
|
||||
- `runMatching`:
|
||||
- pomija tego dancera (dancerHeats.length === 0 → continue)
|
||||
- zwraca pustą tablicę suggestions (bo nikt realnie nie tańczy)
|
||||
- albo zero sugestii dla tego usera – zależnie jak interpretujesz
|
||||
|
||||
---
|
||||
|
||||
#### TC18: Kilka heatów jednego tancerza – wszystkie przypisane
|
||||
|
||||
**Setup:**
|
||||
- 1 dancer z 3 heatami: 5, 7, 9
|
||||
- 2 recorderów, Basic, brak kolizji, wystarczające limity
|
||||
- Stats 0/0
|
||||
|
||||
**Oczekiwania:**
|
||||
- `runMatching` zwraca 3 sugestie (po jednej na heat)
|
||||
- Każdy heat ma przypisanego jakiegoś recordera (nie NOT_FOUND)
|
||||
- W zależności od logiki load-balancingu:
|
||||
- spodziewasz się, że recorderzy podzielą się mniej więcej po równo (np. 2-1)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
Recommended order of implementation:
|
||||
|
||||
### Phase 1: Fundamentals (TC1-3)
|
||||
- Basic happy path
|
||||
- NOT_FOUND scenarios
|
||||
- Self-recording prevention
|
||||
|
||||
### Phase 2: Collision Detection (TC4-9)
|
||||
- Same heat collision
|
||||
- Buffer zones (BEFORE/AFTER)
|
||||
- Division slot mapping
|
||||
|
||||
### Phase 3: Limits & Workload (TC10-11)
|
||||
- MAX_RECORDINGS_PER_PERSON
|
||||
- Recording-recording collision (critical bug fix verification)
|
||||
|
||||
### Phase 4: Fairness & Tiers (TC12-16)
|
||||
- Fairness debt calculation
|
||||
- Tier penalties
|
||||
- Sorting priority verification
|
||||
|
||||
### Phase 5: Edge Cases (TC17-18)
|
||||
- Edge cases and sanity checks
|
||||
|
||||
## Test Data Helpers
|
||||
|
||||
Consider creating helper functions for test setup:
|
||||
|
||||
```javascript
|
||||
// Example helpers needed:
|
||||
function createTestEvent(options) { ... }
|
||||
function createTestParticipant(userId, options) { ... }
|
||||
function createTestHeat(participantId, heatNumber, options) { ... }
|
||||
function mockRecordingStats(userId, done, received) { ... }
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- These tests require database setup (use test database or transactions with rollback)
|
||||
- Consider using Jest's `beforeEach`/`afterEach` for cleanup
|
||||
- Mock `getRecordingStatsForUsers` if needed for deterministic fairness testing
|
||||
- Use descriptive test names matching TC numbers for traceability
|
||||
Reference in New Issue
Block a user