ttrpg-initiative-tracker/shared/tests/turn.characterization.test.js

// Characterization tests for shared/turn.js.
// Lock CURRENT behavior (bugs included). M3 will extend, M4 will fix.
// These tests assert what the code does NOW, not what it SHOULD do.

const shared = require('@ttrpg/shared');
const {
  sortParticipantsByInitiative,
  computeTurnOrderAfterRemoval,
  computeTurnOrderAfterAddition,
  startEncounter,
  nextTurn,
  togglePause,
  addParticipant,
  removeParticipant,
  toggleParticipantActive,
  applyHpChange,
  deathSave,
  toggleCondition,
  reorderParticipants,
  endEncounter,
  makeParticipant,
} = shared;

// Helper: minimal encounter with given participants.
function enc(participants = [], extra = {}) {
  return {
    name: 'Test Encounter',
    participants,
    isStarted: false,
    isPaused: false,
    round: 0,
    currentTurnParticipantId: null,
    turnOrderIds: [],
    ...extra,
  };
}

function p(id, initiative, extra = {}) {
  return makeParticipant({
    id, name: id, type: 'monster',
    initiative, maxHp: 20, currentHp: 20,
    ...extra,
  });
}

describe('sortParticipantsByInitiative', () => {
  test('higher initiative first', () => {
    const ps = [p('a', 5), p('b', 15), p('c', 10)];
    const sorted = sortParticipantsByInitiative(ps, ps);
    expect(sorted.map(x => x.id)).toEqual(['b', 'c', 'a']);
  });

  test('ties broken by original order', () => {
    const ps = [p('a', 10), p('b', 10), p('c', 10)];
    const sorted = sortParticipantsByInitiative(ps, ps);
    expect(sorted.map(x => x.id)).toEqual(['a', 'b', 'c']);
  });
});

describe('startEncounter', () => {
  test('throws if no participants', () => {
    expect(() => startEncounter(enc([]))).toThrow('participants');
  });

  test('throws if no active participants', () => {
    const e = enc([p('a', 10, { isActive: false })]);
    expect(() => startEncounter(e)).toThrow('active');
  });

  test('sets round 1, turn order sorted, current = highest init', () => {
    const ps = [p('a', 5), p('b', 15), p('c', 10)];
    const e = enc(ps);
    const { patch } = startEncounter(e);
    expect(patch.isStarted).toBe(true);
    expect(patch.round).toBe(1);
    expect(patch.turnOrderIds).toEqual(['b', 'c', 'a']);
    expect(patch.currentTurnParticipantId).toBe('b');
  });

  test('inactive excluded from turn order', () => {
    const ps = [p('a', 5), p('b', 15, { isActive: false }), p('c', 10)];
    const { patch } = startEncounter(enc(ps));
    expect(patch.turnOrderIds).toEqual(['c', 'a']);
    expect(patch.currentTurnParticipantId).toBe('c');
  });
});

describe('nextTurn', () => {
  test('throws if not started', () => {
    expect(() => nextTurn(enc([p('a', 10)], { isStarted: false }))).toThrow();
  });

  test('throws if paused', () => {
    expect(() => nextTurn(enc([p('a', 10)], { isStarted: true, isPaused: true, currentTurnParticipantId: 'a', turnOrderIds: ['a'] }))).toThrow();
  });

  test('advances to next in order, no round bump', () => {
    const ps = [p('a', 5), p('b', 15), p('c', 10)];
    const e = enc(ps, {
      isStarted: true,
      round: 1,
      currentTurnParticipantId: 'b',
      turnOrderIds: ['b', 'c', 'a'],
    });
    const { patch } = nextTurn(e);
    expect(patch.currentTurnParticipantId).toBe('c');
    expect(patch.round).toBe(1);
  });

  test('wraps round when last in order', () => {
    const ps = [p('a', 5), p('b', 15), p('c', 10)];
    const e = enc(ps, {
      isStarted: true,
      round: 1,
      currentTurnParticipantId: 'a',
      turnOrderIds: ['b', 'c', 'a'],
    });
    const { patch } = nextTurn(e);
    expect(patch.currentTurnParticipantId).toBe('b');
    expect(patch.round).toBe(2);
  });

  test('ends encounter if no active participants', () => {
    const ps = [p('a', 10, { isActive: false })];
    const e = enc(ps, {
      isStarted: true,
      round: 1,
      currentTurnParticipantId: 'a',
      turnOrderIds: ['a'],
    });
    const { patch } = nextTurn(e);
    expect(patch.isStarted).toBe(false);
    expect(patch.currentTurnParticipantId).toBe(null);
  });
});

describe('togglePause', () => {
  test('pauses started encounter', () => {
    const e = enc([p('a', 10)], { isStarted: true, isPaused: false });
    const { patch } = togglePause(e);
    expect(patch.isPaused).toBe(true);
  });

  test('resume preserves turn order (no re-sort)', () => {
    // BUG-5 fix: resume no longer re-sorts. Re-sort displaced current pointer
    // and caused skips. Order frozen at startEncounter, patched incrementally.
    const ps = [p('a', 5), p('b', 15)];
    const e = enc(ps, { isStarted: true, isPaused: true, turnOrderIds: ['a', 'b'] });
    const { patch } = togglePause(e);
    expect(patch.isPaused).toBe(false);
    expect(patch.turnOrderIds).toEqual(['a', 'b']);
  });
});

describe('removeParticipant', () => {
  test('removes from participants array', () => {
    const ps = [p('a', 10), p('b', 5)];
    const { patch } = removeParticipant(enc(ps), 'a');
    expect(patch.participants.map(x => x.id)).toEqual(['b']);
  });

  test('not started: no turn order mutation', () => {
    const ps = [p('a', 10), p('b', 5)];
    const { patch } = removeParticipant(enc(ps), 'a');
    expect(patch.turnOrderIds).toBeUndefined();
  });

  test('started: removes from turnOrderIds', () => {
    const ps = [p('a', 10), p('b', 5)];
    const e = enc(ps, { isStarted: true, turnOrderIds: ['a', 'b'], currentTurnParticipantId: 'b' });
    const { patch } = removeParticipant(e, 'a');
    expect(patch.turnOrderIds).toEqual(['b']);
  });

  test('started: removing current picks next active', () => {
    const ps = [p('a', 10), p('b', 5), p('c', 3)];
    const e = enc(ps, { isStarted: true, turnOrderIds: ['a', 'b', 'c'], currentTurnParticipantId: 'a' });
    const { patch } = removeParticipant(e, 'a');
    expect(patch.currentTurnParticipantId).toBe('b');
  });
});

describe('toggleParticipantActive', () => {
  test('deactivates participant', () => {
    const ps = [p('a', 10, { isActive: true })];
    const { patch } = toggleParticipantActive(enc(ps), 'a');
    expect(patch.participants[0].isActive).toBe(false);
  });

  test('started: deactivating current advances turn', () => {
    const ps = [p('a', 10), p('b', 5)];
    const e = enc(ps, { isStarted: true, turnOrderIds: ['a', 'b'], currentTurnParticipantId: 'a' });
    const { patch } = toggleParticipantActive(e, 'a');
    expect(patch.currentTurnParticipantId).toBe('b');
  });

  test('started: reactivating inserts by initiative', () => {
    // BUG-5 fix: reactivated participant slots by initiative (not appended
    // to end). Preserves correct rotation order.
    const ps = [p('a', 10, { isActive: false }), p('b', 5)];
    const e = enc(ps, { isStarted: true, turnOrderIds: ['b'], currentTurnParticipantId: 'b' });
    const { patch } = toggleParticipantActive(e, 'a');
    // a init=10 > b init=5 → a slots before b
    expect(patch.turnOrderIds).toEqual(['a', 'b']);
  });
});

describe('applyHpChange', () => {
  test('damage reduces hp, clamps 0', () => {
    const ps = [p('a', 10, { currentHp: 15, maxHp: 20 })];
    const { patch } = applyHpChange(enc(ps), 'a', 'damage', 5);
    expect(patch.participants[0].currentHp).toBe(10);
  });

  test('damage to 0 keeps active + stays in turn order (FEAT-1)', () => {
    // FEAT-1: death no longer deactivates or removes from turn order.
    // Dead stay in rotation, nextTurn still visits them, PCs get death-save turn.
    const ps = [p('a', 10, { currentHp: 3 }), p('b', 5)];
    const e = enc(ps, { isStarted: true, turnOrderIds: ['a', 'b'], currentTurnParticipantId: 'a' });
    const { patch } = applyHpChange(e, 'a', 'damage', 5);
    expect(patch.participants[0].currentHp).toBe(0);
    expect(patch.participants[0].isActive).toBe(true);
    expect(patch.turnOrderIds).toBeUndefined();
    expect(patch.currentTurnParticipantId).toBeUndefined();
  });

  test('heal above 0 resets death saves, keeps active (FEAT-1)', () => {
    // FEAT-1: revive no longer flips isActive (was already active — death
    // doesn't deactivate). deathSaves still reset.
    const ps = [p('a', 10, { currentHp: 0, deathSaves: 2 })];
    const { patch } = applyHpChange(enc(ps), 'a', 'heal', 5);
    expect(patch.participants[0].currentHp).toBe(5);
    expect(patch.participants[0].isActive).toBe(true);
    expect(patch.participants[0].deathSaves).toBe(0);
  });

  test('heal clamps to maxHp', () => {
    const ps = [p('a', 10, { currentHp: 18, maxHp: 20 })];
    const { patch } = applyHpChange(enc(ps), 'a', 'heal', 10);
    expect(patch.participants[0].currentHp).toBe(20);
  });

  test('zero amount = no-op', () => {
    const ps = [p('a', 10, { currentHp: 10 })];
    const { patch } = applyHpChange(enc(ps), 'a', 'damage', 0);
    expect(patch).toBe(null);
  });
});

describe('deathSave', () => {
  test('increments saves', () => {
    const ps = [p('a', 10, { currentHp: 0, deathSaves: 0 })];
    const { patch } = deathSave(enc(ps), 'a', 1);
    expect(patch.participants[0].deathSaves).toBe(1);
  });

  test('clicking same save decrements (toggle)', () => {
    const ps = [p('a', 10, { currentHp: 0, deathSaves: 2 })];
    const { patch } = deathSave(enc(ps), 'a', 2);
    expect(patch.participants[0].deathSaves).toBe(1);
  });

  test('third save sets isDying', () => {
    const ps = [p('a', 10, { currentHp: 0, deathSaves: 2 })];
    const result = deathSave(enc(ps), 'a', 3);
    expect(result.patch.participants[0].deathSaves).toBe(3);
    expect(result.patch.participants[0].isDying).toBe(true);
    expect(result.isDying).toBe(true);
  });
});

describe('toggleCondition', () => {
  test('adds condition', () => {
    const ps = [p('a', 10, { conditions: [] })];
    const { patch } = toggleCondition(enc(ps), 'a', 'poisoned');
    expect(patch.participants[0].conditions).toEqual(['poisoned']);
  });

  test('removes condition', () => {
    const ps = [p('a', 10, { conditions: ['poisoned', 'blinded'] })];
    const { patch } = toggleCondition(enc(ps), 'a', 'poisoned');
    expect(patch.participants[0].conditions).toEqual(['blinded']);
  });
});

describe('reorderParticipants', () => {
  test('swaps within same initiative', () => {
    const ps = [p('a', 10), p('b', 10), p('c', 10)];
    const { patch } = reorderParticipants(enc(ps), 'a', 'c');
    expect(patch.participants.map(x => x.id)).toEqual(['b', 'c', 'a']);
  });

  test('throws if different initiative', () => {
    const ps = [p('a', 10), p('b', 5)];
    expect(() => reorderParticipants(enc(ps), 'a', 'b')).toThrow('same initiative');
  });
});

describe('endEncounter', () => {
  test('resets all combat state', () => {
    const e = enc([p('a', 10)], {
      isStarted: true, round: 5, currentTurnParticipantId: 'a', turnOrderIds: ['a'],
    });
    const { patch } = endEncounter(e);
    expect(patch.isStarted).toBe(false);
    expect(patch.round).toBe(0);
    expect(patch.currentTurnParticipantId).toBe(null);
    expect(patch.turnOrderIds).toEqual([]);
  });
});

describe('computeTurnOrderAfterRemoval', () => {
  test('not started = empty', () => {
    const out = computeTurnOrderAfterRemoval(enc([]), 'a', []);
    expect(out).toEqual({});
  });

  test('removing non-current only filters turnOrderIds', () => {
    const e = enc([], { isStarted: true, turnOrderIds: ['a', 'b'], currentTurnParticipantId: 'b' });
    const out = computeTurnOrderAfterRemoval(e, 'a', []);
    expect(out).toEqual({ turnOrderIds: ['b'] });
  });
});

describe('computeTurnOrderAfterAddition', () => {
  test('not started = empty', () => {
    const out = computeTurnOrderAfterAddition(enc([]), 'a');
    expect(out).toEqual({});
  });

  test('appends if not present', () => {
    const e = enc([], { isStarted: true, turnOrderIds: ['b'] });
    const out = computeTurnOrderAfterAddition(e, 'a');
    expect(out).toEqual({ turnOrderIds: ['b', 'a'] });
  });

  test('no-op if already present', () => {
    const e = enc([], { isStarted: true, turnOrderIds: ['a', 'b'] });
    const out = computeTurnOrderAfterAddition(e, 'a');
    expect(out).toEqual({});
  });
});

describe('addParticipant', () => {
  test('appends participant', () => {
    const np = p('z', 7);
    const { patch } = addParticipant(enc([p('a', 10)]), np);
    expect(patch.participants.map(x => x.id)).toEqual(['a', 'z']);
  });

  test('rejects duplicate id (skip-bug root cause)', () => {
    // Two participants with same id → togglePause resume rebuilds order with
    // dup id twice → nextTurn gets stuck repeating that id forever.
    // Audit found this in 100-round replay (addParticipant fired while paused
    // because nextTurn threw, loop spun, same totalTurns %10 → re-added).
    const existing = p('x', 5);
    const dup = makeParticipant({ id: 'x', name: 'x2', type: 'monster', initiative: 10, maxHp: 100, currentHp: 100 });
    expect(() => addParticipant(enc([p('a', 10), existing]), dup)).toThrow();
  });
});