test: added tests for the ProgramStore

also added documentation

ref: N25B-428

test/utils/programStore.test.ts

@@ -0,0 +1,100 @@
+import useProgramStore, {type ReducedProgram} from "../../src/utils/programStore.ts";
+
+
+describe('useProgramStore', () => {
+  beforeEach(() => {
+    // Reset store before each test
+    useProgramStore.setState({
+      currentProgram: { phases: [] },
+    });
+  });
+
+  const mockProgram: ReducedProgram = {
+    phases: [
+      {
+        id: 'phase-1',
+        norms: [{ id: 'norm-1' }],
+        goals: [{ id: 'goal-1' }],
+        triggers: [{ id: 'trigger-1' }],
+      },
+      {
+        id: 'phase-2',
+        norms: [{ id: 'norm-2' }],
+        goals: [{ id: 'goal-2' }],
+        triggers: [{ id: 'trigger-2' }],
+      },
+    ],
+  };
+
+  it('should set and get the program state', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    const program = useProgramStore.getState().getProgramState();
+    expect(program).toEqual(mockProgram);
+  });
+
+  it('should return the ids of all phases in the program', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    const phaseIds = useProgramStore.getState().getPhaseIds();
+    expect(phaseIds).toEqual(['phase-1', 'phase-2']);
+  });
+
+  it('should return all norms for a given phase', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    const norms = useProgramStore.getState().getNormsInPhase('phase-1');
+    expect(norms).toEqual([{ id: 'norm-1' }]);
+  });
+
+  it('should return all goals for a given phase', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    const goals = useProgramStore.getState().getGoalsInPhase('phase-2');
+    expect(goals).toEqual([{ id: 'goal-2' }]);
+  });
+
+  it('should return all triggers for a given phase', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    const triggers = useProgramStore.getState().getTriggersInPhase('phase-1');
+    expect(triggers).toEqual([{ id: 'trigger-1' }]);
+  });
+
+  it('throws if phase does not exist when getting norms', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    expect(() =>
+      useProgramStore.getState().getNormsInPhase('missing-phase')
+    ).toThrow('phase with id:"missing-phase" not found');
+  });
+
+  it('throws if phase does not exist when getting goals', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    expect(() =>
+      useProgramStore.getState().getGoalsInPhase('missing-phase')
+    ).toThrow('phase with id:"missing-phase" not found');
+  });
+
+  it('throws if phase does not exist when getting triggers', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    expect(() =>
+      useProgramStore.getState().getTriggersInPhase('missing-phase')
+    ).toThrow('phase with id:"missing-phase" not found');
+  });
+
+  // this test should be at the bottom to avoid conflicts with the previous tests
+  it('should clone program state when setting it (no shared references should exist)', () => {
+    useProgramStore.getState().setProgramState(mockProgram);
+
+    const storedProgram = useProgramStore.getState().getProgramState();
+
+    // mutate original
+    (mockProgram.phases[0].norms as any[]).push({ id: 'norm-mutated' });
+
+    // store should NOT change
+    expect(storedProgram.phases[0]['norms']).toHaveLength(1);
+  });
+});