@studious-lms/server 1.21.0 → 1.23.0

package/tests/unit/services/gradeCalculation.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from "vitest";
+import {
+  computeFinalGrade,
+  resolveLetterGrade,
+  roundPercentage,
+  type GradeCalculationPolicies,
+  type GradeCategoryInput,
+  type ScoreInput,
+} from "../../../src/services/gradeCalculation.js";
+
+const noPolicies: GradeCalculationPolicies = {
+  treatMissingAsZero: false,
+  roundingMode: "NONE",
+};
+
+const categories: GradeCategoryInput[] = [
+  { id: "hw", name: "Homework", weight: 40, dropLowest: 0 },
+  { id: "exam", name: "Exams", weight: 60, dropLowest: 0 },
+];
+
+describe("computeFinalGrade", () => {
+  it("returns null percentage with no scores", () => {
+    const result = computeFinalGrade(noPolicies, categories, []);
+    expect(result.percentage).toBeNull();
+    expect(result.categories).toHaveLength(2);
+    expect(result.categories[0].average).toBeNull();
+  });
+
+  it("computes weighted average of category averages", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 }, // 80%
+      { categoryId: "exam", pointsEarned: 50, maxPoints: 100 }, // 50%
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    // 80 * 0.4 + 50 * 0.6 = 62
+    expect(result.percentage).toBeCloseTo(62);
+  });
+
+  it("puts uncategorized scores into a default category with weight 1", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 10, maxPoints: 10 }, // 100%
+      { categoryId: null, pointsEarned: 5, maxPoints: 10 }, // 50%
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    // (100 * 40 + 50 * 1) / 41
+    expect(result.percentage).toBeCloseTo((100 * 40 + 50) / 41);
+    const fallback = result.categories.find((c) => c.categoryId === null);
+    expect(fallback?.average).toBeCloseTo(50);
+    expect(fallback?.weight).toBe(1);
+  });
+
+  it("treats unknown category ids as uncategorized", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "deleted", pointsEarned: 5, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === null)?.average
+    ).toBeCloseTo(50);
+  });
+
+  it("excludes missing scores by default", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 },
+      { categoryId: "hw", pointsEarned: null, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(80);
+  });
+
+  it("counts missing scores as zero when treatMissingAsZero is set", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 },
+      { categoryId: "hw", pointsEarned: null, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(
+      { ...noPolicies, treatMissingAsZero: true },
+      categories,
+      scores
+    );
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(40);
+  });
+
+  it("respects per-score weights within a category", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 10, maxPoints: 10, weight: 3 }, // 100%
+      { categoryId: "hw", pointsEarned: 0, maxPoints: 10, weight: 1 }, // 0%
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(75);
+  });
+
+  it("drops the lowest N scores in a category", () => {
+    const dropCategories: GradeCategoryInput[] = [
+      { id: "hw", name: "Homework", weight: 1, dropLowest: 1 },
+    ];
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 10, maxPoints: 10 }, // 100%
+      { categoryId: "hw", pointsEarned: 2, maxPoints: 10 }, // 20% (dropped)
+      { categoryId: "hw", pointsEarned: 6, maxPoints: 10 }, // 60%
+    ];
+    const result = computeFinalGrade(noPolicies, dropCategories, scores);
+    expect(result.percentage).toBeCloseTo(80);
+    expect(result.categories[0].droppedScores).toBe(1);
+    expect(result.categories[0].countedScores).toBe(2);
+  });
+
+  it("never drops every score in a category", () => {
+    const dropCategories: GradeCategoryInput[] = [
+      { id: "hw", name: "Homework", weight: 1, dropLowest: 5 },
+    ];
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 4, maxPoints: 10 },
+      { categoryId: "hw", pointsEarned: 8, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, dropCategories, scores);
+    expect(result.percentage).toBeCloseTo(80);
+    expect(result.categories[0].droppedScores).toBe(1);
+  });
+
+  it("ignores scores with non-positive maxPoints", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 5, maxPoints: 0 },
+      { categoryId: "hw", pointsEarned: 9, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(
+      result.categories.find((c) => c.categoryId === "hw")?.average
+    ).toBeCloseTo(90);
+  });
+
+  it("excludes empty categories from the weighted average", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 9, maxPoints: 10 },
+    ];
+    const result = computeFinalGrade(noPolicies, categories, scores);
+    expect(result.percentage).toBeCloseTo(90);
+  });
+
+  it("applies the rounding mode to the final percentage", () => {
+    const scores: ScoreInput[] = [
+      { categoryId: "hw", pointsEarned: 5, maxPoints: 6 }, // 83.33%
+    ];
+    expect(
+      computeFinalGrade(
+        { ...noPolicies, roundingMode: "FLOOR" },
+        categories,
+        scores
+      ).percentage
+    ).toBe(83);
+    expect(
+      computeFinalGrade(
+        { ...noPolicies, roundingMode: "CEILING" },
+        categories,
+        scores
+      ).percentage
+    ).toBe(84);
+    expect(
+      computeFinalGrade(
+        { ...noPolicies, roundingMode: "HALF_UP" },
+        categories,
+        scores
+      ).percentage
+    ).toBe(83);
+  });
+});
+
+describe("roundPercentage", () => {
+  it("rounds according to mode", () => {
+    expect(roundPercentage(89.5, "HALF_UP")).toBe(90);
+    expect(roundPercentage(89.9, "FLOOR")).toBe(89);
+    expect(roundPercentage(89.1, "CEILING")).toBe(90);
+    expect(roundPercentage(89.123, "NONE")).toBeCloseTo(89.123);
+  });
+});
+
+describe("resolveLetterGrade", () => {
+  const structured = JSON.stringify({
+    boundaries: [
+      { grade: "A", minPercentage: 90, maxPercentage: 100 },
+      { grade: "B", minPercentage: 80, maxPercentage: 89 },
+      { grade: "C", minPercentage: 70, maxPercentage: 79 },
+    ],
+  });
+
+  it("maps percentages to letters", () => {
+    expect(resolveLetterGrade(structured, 95)).toBe("A");
+    expect(resolveLetterGrade(structured, 85)).toBe("B");
+    expect(resolveLetterGrade(structured, 70)).toBe("C");
+  });
+
+  it("returns null below all boundaries", () => {
+    expect(resolveLetterGrade(structured, 10)).toBeNull();
+  });
+
+  it("returns null for malformed payloads", () => {
+    expect(resolveLetterGrade("not json", 90)).toBeNull();
+    expect(resolveLetterGrade("{}", 90)).toBeNull();
+  });
+});