diff --git a/__tests__/apiErrors.test.js b/__tests__/apiErrors.test.js
new file mode 100644
index 000000000..205df8ea5
--- /dev/null
+++ b/__tests__/apiErrors.test.js
@@ -0,0 +1,131 @@
+// __tests__/apiErrors.test.js
+//
+// Run with:  npx jest __tests__/apiErrors.test.js
+//
+// Tests the ApiError subclasses in src/lib/apiErrors.js.
+
+const { describe, expect, test } = require("@jest/globals");
+const {
+  ApiError,
+  AuthError,
+  RateLimitError,
+  ValidationError,
+  ConfigError,
+} = require("../src/lib/apiErrors.js");
+
+describe("ApiError", () => {
+  test("sets name, message, code and status from constructor args", () => {
+    const err = new ApiError("Something broke", "SOMETHING_BROKE", 503);
+    expect(err.name).toBe("ApiError");
+    expect(err.message).toBe("Something broke");
+    expect(err.code).toBe("SOMETHING_BROKE");
+    expect(err.status).toBe(503);
+  });
+
+  test("uses defaults when only message is provided", () => {
+    const err = new ApiError("Generic error");
+    expect(err.code).toBe("INTERNAL_ERROR");
+    expect(err.status).toBe(500);
+  });
+
+  test("uses all defaults when no args provided", () => {
+    const err = new ApiError();
+    expect(err.message).toBe("");
+    expect(err.code).toBe("INTERNAL_ERROR");
+    expect(err.status).toBe(500);
+  });
+
+  test("is an instance of Error", () => {
+    const err = new ApiError("test");
+    expect(err instanceof Error).toBe(true);
+    expect(err instanceof ApiError).toBe(true);
+  });
+});
+
+describe("AuthError", () => {
+  test("sets 401 status and AUTH_ERROR code", () => {
+    const err = new AuthError("Invalid token");
+    expect(err.name).toBe("AuthError");
+    expect(err.message).toBe("Invalid token");
+    expect(err.code).toBe("AUTH_ERROR");
+    expect(err.status).toBe(401);
+  });
+
+  test("uses default message when none provided", () => {
+    const err = new AuthError();
+    expect(err.message).toBe("Unauthorized");
+    expect(err.status).toBe(401);
+  });
+
+  test("is an instance of ApiError and Error", () => {
+    const err = new AuthError();
+    expect(err instanceof ApiError).toBe(true);
+    expect(err instanceof Error).toBe(true);
+  });
+});
+
+describe("RateLimitError", () => {
+  test("sets 429 status and RATE_LIMIT code", () => {
+    const err = new RateLimitError("Slow down");
+    expect(err.name).toBe("RateLimitError");
+    expect(err.message).toBe("Slow down");
+    expect(err.code).toBe("RATE_LIMIT");
+    expect(err.status).toBe(429);
+  });
+
+  test("uses default message when none provided", () => {
+    const err = new RateLimitError();
+    expect(err.message).toBe("Too many requests");
+    expect(err.status).toBe(429);
+  });
+
+  test("is an instance of ApiError and Error", () => {
+    const err = new RateLimitError();
+    expect(err instanceof ApiError).toBe(true);
+    expect(err instanceof Error).toBe(true);
+  });
+});
+
+describe("ValidationError", () => {
+  test("sets 400 status and VALIDATION_ERROR code", () => {
+    const err = new ValidationError("Email is required");
+    expect(err.name).toBe("ValidationError");
+    expect(err.message).toBe("Email is required");
+    expect(err.code).toBe("VALIDATION_ERROR");
+    expect(err.status).toBe(400);
+  });
+
+  test("uses default message when none provided", () => {
+    const err = new ValidationError();
+    expect(err.message).toBe("Validation failed");
+    expect(err.status).toBe(400);
+  });
+
+  test("is an instance of ApiError and Error", () => {
+    const err = new ValidationError();
+    expect(err instanceof ApiError).toBe(true);
+    expect(err instanceof Error).toBe(true);
+  });
+});
+
+describe("ConfigError", () => {
+  test("sets 500 status and CONFIG_ERROR code", () => {
+    const err = new ConfigError("Missing DB URL");
+    expect(err.name).toBe("ConfigError");
+    expect(err.message).toBe("Missing DB URL");
+    expect(err.code).toBe("CONFIG_ERROR");
+    expect(err.status).toBe(500);
+  });
+
+  test("uses default message when none provided", () => {
+    const err = new ConfigError();
+    expect(err.message).toBe("Server configuration error");
+    expect(err.status).toBe(500);
+  });
+
+  test("is an instance of ApiError and Error", () => {
+    const err = new ConfigError();
+    expect(err instanceof ApiError).toBe(true);
+    expect(err instanceof Error).toBe(true);
+  });
+});
diff --git a/__tests__/profileUtils.test.js b/__tests__/profileUtils.test.js
new file mode 100644
index 000000000..61787bb09
--- /dev/null
+++ b/__tests__/profileUtils.test.js
@@ -0,0 +1,357 @@
+// __tests__/profileUtils.test.js
+//
+// Run with:  npx jest __tests__/profileUtils.test.js
+//
+// Tests the profile utility functions in src/lib/profileUtils.js.
+
+const { describe, expect, test } = require("@jest/globals");
+const {
+  AVATAR_BUCKET,
+  MAX_AVATAR_FILE_SIZE,
+  MAX_AVATAR_URL_LENGTH,
+  MAX_PROFILE_URL_LENGTH,
+  MAX_BIO_LENGTH,
+  PROFILE_URL_FIELDS,
+  PRESET_PROJECT_GRADIENTS,
+  EMPTY_PROJECT,
+  CODING_PLATFORMS,
+  ONBOARDING_OPTIONAL_FIELDS,
+  ONBOARDING_REQUIRED_FIELDS,
+  EMPTY_PROFILE_FORM,
+  safeAvatarUrl,
+  safeExternalUrl,
+  sanitizeProfileLinks,
+  buildFormDataFromUser,
+  normalizeProfilePayload,
+  validateProfileForm,
+  isOnboardingStep1Valid,
+  shouldShowProfileSetup,
+} = require("../src/lib/profileUtils.js");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+describe("profileUtils constants", () => {
+  test("AVATAR_BUCKET is 'avatars'", () => {
+    expect(AVATAR_BUCKET).toBe("avatars");
+  });
+
+  test("MAX_AVATAR_FILE_SIZE is 2MB", () => {
+    expect(MAX_AVATAR_FILE_SIZE).toBe(2 * 1024 * 1024);
+  });
+
+  test("MAX_AVATAR_URL_LENGTH and MAX_PROFILE_URL_LENGTH are positive", () => {
+    expect(MAX_AVATAR_URL_LENGTH).toBeGreaterThan(0);
+    expect(MAX_PROFILE_URL_LENGTH).toBeGreaterThan(0);
+  });
+
+  test("MAX_BIO_LENGTH is a reasonable limit", () => {
+    expect(MAX_BIO_LENGTH).toBe(300);
+  });
+
+  test("PROFILE_URL_FIELDS contains expected fields", () => {
+    expect(PROFILE_URL_FIELDS).toContain("resume_link");
+    expect(PROFILE_URL_FIELDS).toContain("github_profile");
+    expect(PROFILE_URL_FIELDS).toContain("linkedin_profile");
+  });
+
+  test("PRESET_PROJECT_GRADIENTS has at least one entry", () => {
+    expect(PRESET_PROJECT_GRADIENTS.length).toBeGreaterThan(0);
+  });
+
+  test("EMPTY_PROJECT has required keys", () => {
+    expect(EMPTY_PROJECT).toHaveProperty("title");
+    expect(EMPTY_PROJECT).toHaveProperty("subtitle");
+    expect(EMPTY_PROJECT).toHaveProperty("tags");
+    expect(EMPTY_PROJECT).toHaveProperty("url");
+    expect(EMPTY_PROJECT).toHaveProperty("preview");
+  });
+
+  test("CODING_PLATFORMS is a non-empty array", () => {
+    expect(Array.isArray(CODING_PLATFORMS)).toBe(true);
+    expect(CODING_PLATFORMS.length).toBeGreaterThan(0);
+  });
+
+  test("ONBOARDING_REQUIRED_FIELDS includes 'name' and 'skills'", () => {
+    expect(ONBOARDING_REQUIRED_FIELDS).toContain("name");
+    expect(ONBOARDING_REQUIRED_FIELDS).toContain("skills");
+  });
+
+  test("EMPTY_PROFILE_FORM has all required fields", () => {
+    expect(EMPTY_PROFILE_FORM).toHaveProperty("name");
+    expect(EMPTY_PROFILE_FORM).toHaveProperty("skills");
+    expect(EMPTY_PROFILE_FORM).toHaveProperty("email_notifications");
+    expect(EMPTY_PROFILE_FORM).toHaveProperty("avatar_url");
+    expect(EMPTY_PROFILE_FORM).toHaveProperty("projects");
+  });
+});
+
+// ── safeAvatarUrl ────────────────────────────────────────────────────────────
+
+describe("safeAvatarUrl", () => {
+  test("returns a valid URL unchanged", () => {
+    expect(safeAvatarUrl("https://example.com/avatar.png")).toBe("https://example.com/avatar.png");
+  });
+
+  test("returns empty string for non-string input", () => {
+    expect(safeAvatarUrl(null)).toBe("");
+    expect(safeAvatarUrl(undefined)).toBe("");
+    expect(safeAvatarUrl(123)).toBe("");
+    expect(safeAvatarUrl({})).toBe("");
+  });
+
+  test("returns empty string for data URL", () => {
+    expect(safeAvatarUrl("data:image/png;base64,abc123")).toBe("");
+    expect(safeAvatarUrl("data:text/html,<script>")).toBe("");
+  });
+
+  test("returns empty string for overly long URL", () => {
+    const longUrl = "https://example.com/" + "x".repeat(MAX_AVATAR_URL_LENGTH);
+    expect(safeAvatarUrl(longUrl)).toBe("");
+  });
+
+  test("returns trimmed URL within length limit", () => {
+    const shortUrl = "https://example.com/avatar.png";
+    expect(safeAvatarUrl(shortUrl)).toBe(shortUrl);
+  });
+});
+
+// ── safeExternalUrl ────────────────────────────────────────────────────────
+
+describe("safeExternalUrl", () => {
+  test("returns valid http URL unchanged", () => {
+    expect(safeExternalUrl("http://example.com/page")).toBe("http://example.com/page");
+  });
+
+  test("returns valid https URL unchanged", () => {
+    expect(safeExternalUrl("https://github.com/user")).toBe("https://github.com/user");
+  });
+
+  test("returns empty string for non-string input", () => {
+    expect(safeExternalUrl(null)).toBe("");
+    expect(safeExternalUrl(undefined)).toBe("");
+    expect(safeExternalUrl(123)).toBe("");
+  });
+
+  test("returns empty string for file:// URLs", () => {
+    expect(safeExternalUrl("file:///etc/passwd")).toBe("");
+  });
+
+  test("returns empty string for javascript: URLs", () => {
+    expect(safeExternalUrl("javascript:alert(1)")).toBe("");
+  });
+
+  test("returns empty string for ftp:// URLs", () => {
+    expect(safeExternalUrl("ftp://files.example.com")).toBe("");
+  });
+
+  test("returns empty string for overly long URL", () => {
+    const longUrl = "https://example.com/" + "x".repeat(MAX_PROFILE_URL_LENGTH);
+    expect(safeExternalUrl(longUrl)).toBe("");
+  });
+
+  test("returns empty string for invalid URL", () => {
+    expect(safeExternalUrl("not-a-url")).toBe("");
+    expect(safeExternalUrl("just some text")).toBe("");
+  });
+});
+
+// ── sanitizeProfileLinks ────────────────────────────────────────────────────
+
+describe("sanitizeProfileLinks", () => {
+  test("passes through valid URLs and trims whitespace", () => {
+    const result = sanitizeProfileLinks({
+      resume_link: "  https://example.com/resume  ",
+      github_profile: "https://github.com/user",
+      linkedin_profile: "https://linkedin.com/in/user",
+    });
+    expect(result.data).toBeDefined();
+    expect(result.data.resume_link).toBe("https://example.com/resume");
+  });
+
+  test("sets empty string for missing fields", () => {
+    const result = sanitizeProfileLinks({});
+    expect(result.data).toBeDefined();
+    expect(result.data.resume_link).toBe("");
+    expect(result.data.github_profile).toBe("");
+  });
+
+  test("returns error object for invalid URL", () => {
+    const result = sanitizeProfileLinks({
+      resume_link: "not-a-url",
+      github_profile: "",
+      linkedin_profile: "",
+    });
+    expect(result.error).toBeDefined();
+    expect(result.error).toContain("valid http or https URLs");
+  });
+
+  test("returns error for javascript: URL", () => {
+    const result = sanitizeProfileLinks({
+      resume_link: "javascript:alert(1)",
+      github_profile: "",
+      linkedin_profile: "",
+    });
+    expect(result.error).toBeDefined();
+  });
+});
+
+// ── buildFormDataFromUser ───────────────────────────────────────────────────
+
+describe("buildFormDataFromUser", () => {
+  test("returns empty form for null user", () => {
+    const form = buildFormDataFromUser(null);
+    expect(form.name).toBe("");
+  });
+
+  test("returns empty form for user with no metadata", () => {
+    const form = buildFormDataFromUser({});
+    expect(form.name).toBe("");
+  });
+
+  test("extracts metadata fields correctly", () => {
+    const user = {
+      user_metadata: {
+        name: "Alice",
+        skills: "JavaScript, Python",
+        leetcode_username: "alice",
+        codeforces_rating: 1500,
+      },
+    };
+    const form = buildFormDataFromUser(user);
+    expect(form.name).toBe("Alice");
+    expect(form.skills).toBe("JavaScript, Python");
+    expect(form.leetcode_username).toBe("alice");
+    expect(form.codeforces_rating).toBe(1500);
+  });
+
+  test("limits skills to MAX_BIO_LENGTH", () => {
+    const longSkills = "a".repeat(MAX_BIO_LENGTH + 100);
+    const user = { user_metadata: { skills: longSkills } };
+    const form = buildFormDataFromUser(user);
+    expect(form.skills.length).toBeLessThanOrEqual(MAX_BIO_LENGTH);
+  });
+
+  test("uses picture as avatar_url fallback", () => {
+    const user = { user_metadata: { picture: "https://example.com/pic.png" } };
+    const form = buildFormDataFromUser(user);
+    expect(form.avatar_url).toBe("https://example.com/pic.png");
+  });
+
+  test("defaults projects to empty array if not an array", () => {
+    const user = { user_metadata: { projects: "not-an-array" } };
+    const form = buildFormDataFromUser(user);
+    expect(Array.isArray(form.projects)).toBe(true);
+    expect(form.projects.length).toBe(0);
+  });
+});
+
+// ── normalizeProfilePayload ─────────────────────────────────────────────────
+
+describe("normalizeProfilePayload", () => {
+  test("converts numeric strings to numbers", () => {
+    const data = {
+      leetcode_solved: "42",
+      codeforces_rating: "1500",
+      codechef_stars: "3",
+      github_contributions: "100",
+    };
+    const normalized = normalizeProfilePayload(data);
+    expect(normalized.leetcode_solved).toBe(42);
+    expect(normalized.codeforces_rating).toBe(1500);
+    expect(normalized.codechef_stars).toBe(3);
+    expect(normalized.github_contributions).toBe(100);
+  });
+
+  test("converts non-numeric strings to 0", () => {
+    const data = { leetcode_solved: "abc", codeforces_rating: "" };
+    const normalized = normalizeProfilePayload(data);
+    expect(normalized.leetcode_solved).toBe(0);
+    expect(normalized.codeforces_rating).toBe(0);
+  });
+
+  test("preserves non-numeric fields", () => {
+    const data = { name: "Alice", skills: "JS" };
+    const normalized = normalizeProfilePayload(data);
+    expect(normalized.name).toBe("Alice");
+    expect(normalized.skills).toBe("JS");
+  });
+
+  test("ensures projects is always an array", () => {
+    const normalized1 = normalizeProfilePayload({ projects: null });
+    const normalized2 = normalizeProfilePayload({ projects: "not-array" });
+    const normalized3 = normalizeProfilePayload({ projects: ["proj1"] });
+    expect(Array.isArray(normalized1.projects)).toBe(true);
+    expect(Array.isArray(normalized2.projects)).toBe(true);
+    expect(Array.isArray(normalized3.projects)).toBe(true);
+    expect(normalized3.projects).toEqual(["proj1"]);
+  });
+});
+
+// ── validateProfileForm ─────────────────────────────────────────────────────
+
+describe("validateProfileForm", () => {
+  test("returns null for 'edit' mode regardless of content", () => {
+    expect(validateProfileForm({}, "edit")).toBeNull();
+    expect(validateProfileForm({ name: "", skills: "" }, "edit")).toBeNull();
+  });
+
+  test("returns null when required fields are present in onboarding", () => {
+    const form = { name: "Alice", skills: "JavaScript" };
+    expect(validateProfileForm(form, "onboarding")).toBeNull();
+  });
+
+  test("returns error message when name is missing in onboarding", () => {
+    const form = { name: "", skills: "JavaScript" };
+    expect(validateProfileForm(form, "onboarding")).toBe("Full name is required.");
+  });
+
+  test("returns error message when skills is missing in onboarding", () => {
+    const form = { name: "Alice", skills: "" };
+    expect(validateProfileForm(form, "onboarding")).toBe("Bio is required.");
+  });
+
+  test("trims whitespace before validation", () => {
+    expect(validateProfileForm({ name: "   ", skills: "JS" }, "onboarding")).toBe("Full name is required.");
+    expect(validateProfileForm({ name: "Alice", skills: "   " }, "onboarding")).toBe("Bio is required.");
+  });
+});
+
+// ── isOnboardingStep1Valid ──────────────────────────────────────────────────
+
+describe("isOnboardingStep1Valid", () => {
+  test("returns false when required fields are missing", () => {
+    expect(isOnboardingStep1Valid({})).toBe(false);
+    expect(isOnboardingStep1Valid({ name: "", skills: "" })).toBe(false);
+    expect(isOnboardingStep1Valid({ name: "Alice", skills: "" })).toBe(false);
+    expect(isOnboardingStep1Valid({ name: "", skills: "JS" })).toBe(false);
+  });
+
+  test("returns true when all required fields are non-empty", () => {
+    expect(isOnboardingStep1Valid({ name: "Alice", skills: "JavaScript" })).toBe(true);
+  });
+
+  test("returns false for whitespace-only values", () => {
+    expect(isOnboardingStep1Valid({ name: "  ", skills: "JS" })).toBe(false);
+  });
+});
+
+// ── shouldShowProfileSetup ──────────────────────────────────────────────────
+
+describe("shouldShowProfileSetup", () => {
+  test("returns false for null user", () => {
+    expect(shouldShowProfileSetup(null)).toBe(false);
+  });
+
+  test("returns false for undefined user", () => {
+    expect(shouldShowProfileSetup(undefined)).toBe(false);
+  });
+
+  test("returns true when hasSeenProfileSetup is not true", () => {
+    expect(shouldShowProfileSetup({ user_metadata: {} })).toBe(true);
+    expect(shouldShowProfileSetup({ user_metadata: { hasSeenProfileSetup: false } })).toBe(true);
+  });
+
+  test("returns false when hasSeenProfileSetup is true", () => {
+    expect(shouldShowProfileSetup({ user_metadata: { hasSeenProfileSetup: true } })).toBe(false);
+  });
+});
diff --git a/__tests__/random.test.js b/__tests__/random.test.js
new file mode 100644
index 000000000..1b653e0fd
--- /dev/null
+++ b/__tests__/random.test.js
@@ -0,0 +1,73 @@
+// __tests__/random.test.js
+//
+// Run with:  npx jest __tests__/random.test.js
+//
+// Tests the generateSecureCode function in src/lib/random.js.
+
+const { describe, expect, test } = require("@jest/globals");
+const { generateSecureCode } = require("../src/lib/random.js");
+
+const CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+describe("generateSecureCode", () => {
+  test("returns a string", () => {
+    const result = generateSecureCode();
+    expect(typeof result).toBe("string");
+  });
+
+  test("defaults to length 6", () => {
+    expect(generateSecureCode().length).toBe(6);
+  });
+
+  test("respects custom length argument", () => {
+    expect(generateSecureCode(4).length).toBe(4);
+    expect(generateSecureCode(8).length).toBe(8);
+    expect(generateSecureCode(12).length).toBe(12);
+  });
+
+  test("returns empty string for length 0", () => {
+    expect(generateSecureCode(0)).toBe("");
+  });
+
+  test("returns only alphanumeric characters from the expected charset", () => {
+    const code = generateSecureCode(100);
+    for (const char of code) {
+      expect(CHARSET).toContain(char);
+    }
+  });
+
+  test("returns a different code on each call (high probability)", () => {
+    const codes = new Set();
+    for (let i = 0; i < 100; i++) {
+      codes.add(generateSecureCode());
+    }
+    // With 6 chars from 36-char set, collision probability is very low in 100 samples
+    expect(codes.size).toBe(100);
+  });
+
+  test("generates uppercase letters and digits only", () => {
+    const code = generateSecureCode(50);
+    expect(code).toMatch(/^[A-Z0-9]+$/);
+  });
+
+  test("does not include lowercase letters", () => {
+    // Run multiple times to catch any lowercase leakage
+    for (let i = 0; i < 10; i++) {
+      const code = generateSecureCode(20);
+      expect(code).not.toMatch(/[a-z]/);
+    }
+  });
+
+  test("length argument of 1 returns exactly one character", () => {
+    const code = generateSecureCode(1);
+    expect(code.length).toBe(1);
+    expect(CHARSET).toContain(code);
+  });
+
+  test("large length generates all valid characters", () => {
+    const code = generateSecureCode(360);
+    const uniqueChars = new Set(code);
+    // Should cover most of the 36-character charset in 360 samples
+    expect(uniqueChars.size).toBeGreaterThanOrEqual(30);
+  });
+});
diff --git a/__tests__/rateLimits.test.js b/__tests__/rateLimits.test.js
new file mode 100644
index 000000000..5ad4a5f2b
--- /dev/null
+++ b/__tests__/rateLimits.test.js
@@ -0,0 +1,47 @@
+// __tests__/rateLimits.test.js
+//
+// Run with:  npx jest __tests__/rateLimits.test.js
+//
+// Tests the rate limit configuration in src/config/rateLimits.js.
+
+const { describe, expect, test } = require("@jest/globals");
+const { RATE_LIMITS } = require("../src/config/rateLimits.js");
+
+describe("RATE_LIMITS", () => {
+  test("CONTACT_API has a positive LIMIT", () => {
+    expect(RATE_LIMITS.CONTACT_API).toBeDefined();
+    expect(typeof RATE_LIMITS.CONTACT_API.LIMIT).toBe("number");
+    expect(RATE_LIMITS.CONTACT_API.LIMIT).toBeGreaterThan(0);
+  });
+
+  test("SMTP has DAILY_QUOTA with a sensible default", () => {
+    expect(RATE_LIMITS.SMTP).toBeDefined();
+    expect(typeof RATE_LIMITS.SMTP.DAILY_QUOTA).toBe("number");
+    // Default is 400 per the config
+    expect(RATE_LIMITS.SMTP.DAILY_QUOTA).toBe(400);
+  });
+
+  test("has only expected top-level keys", () => {
+    const keys = Object.keys(RATE_LIMITS).sort();
+    expect(keys).toEqual(["CONTACT_API", "SMTP"]);
+  });
+
+  test("CONTACT_API.LIMIT is an integer", () => {
+    expect(Number.isInteger(RATE_LIMITS.CONTACT_API.LIMIT)).toBe(true);
+  });
+
+  test("SMTP.DAILY_QUOTA is an integer", () => {
+    expect(Number.isInteger(RATE_LIMITS.SMTP.DAILY_QUOTA)).toBe(true);
+  });
+
+  test("CONTACT_API.LIMIT is a reasonable small number (anti-abuse)", () => {
+    // A contact API limit should not be huge
+    expect(RATE_LIMITS.CONTACT_API.LIMIT).toBeLessThanOrEqual(100);
+  });
+
+  test("SMTP.DAILY_QUOTA is a reasonable daily volume", () => {
+    // SMTP daily quota should be positive and realistic
+    expect(RATE_LIMITS.SMTP.DAILY_QUOTA).toBeGreaterThan(0);
+    expect(RATE_LIMITS.SMTP.DAILY_QUOTA).toBeGreaterThanOrEqual(100);
+  });
+});
diff --git a/__tests__/sortingGenerators.test.js b/__tests__/sortingGenerators.test.js
new file mode 100644
index 000000000..6706fc844
--- /dev/null
+++ b/__tests__/sortingGenerators.test.js
@@ -0,0 +1,281 @@
+// __tests__/sortingGenerators.test.js
+//
+// Run with:  npx jest __tests__/sortingGenerators.test.js
+//
+// Tests the sorting algorithm generators in src/utils/sortingGenerators.js.
+
+const { describe, expect, test } = require("@jest/globals");
+const {
+  bubbleSortGen,
+  selectionSortGen,
+  insertionSortGen,
+  mergeSortGen,
+  quickSortGen,
+  heapSortGen,
+} = require("../src/utils/sortingGenerators.js");
+
+function collectAllSteps(generator) {
+  return [...generator];
+}
+
+function getFinalArray(generator, inputArr) {
+  const steps = collectAllSteps(generator);
+  if (steps.length === 0) {
+    // Generators yield no steps for empty or single-element inputs;
+    // in that case the array is already sorted (same as input).
+    return inputArr;
+  }
+  return steps.at(-1).array;
+}
+
+// ── Shared helpers ───────────────────────────────────────────────────────────
+
+function isSorted(arr) {
+  for (let i = 0; i < arr.length - 1; i++) {
+    if (arr[i] > arr[i + 1]) return false;
+  }
+  return true;
+}
+
+function hasRequiredStepKeys(step) {
+  return (
+    Array.isArray(step.array) &&
+    typeof step.comparisons === "number" &&
+    typeof step.swaps === "number" &&
+    step.currentIndices !== undefined
+  );
+}
+
+// ── Bubble Sort ─────────────────────────────────────────────────────────────
+
+describe("bubbleSortGen", () => {
+  test("sorts a simple array in ascending order", () => {
+    const result = getFinalArray(bubbleSortGen([5, 3, 8, 4, 2]), [5, 3, 8, 4, 2]);
+    expect(result).toEqual([2, 3, 4, 5, 8]);
+  });
+
+  test("returns sorted array when already sorted", () => {
+    const result = getFinalArray(bubbleSortGen([1, 2, 3]), [1, 2, 3]);
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  test("handles a single element", () => {
+    const result = getFinalArray(bubbleSortGen([42]), [42]);
+    expect(result).toEqual([42]);
+  });
+
+  test("handles an empty array", () => {
+    const result = getFinalArray(bubbleSortGen([]), []);
+    expect(result).toEqual([]);
+  });
+
+  test("handles duplicates", () => {
+    const result = getFinalArray(bubbleSortGen([3, 1, 3, 2, 1]), [3, 1, 3, 2, 1]);
+    expect(isSorted(result)).toBe(true);
+    expect(result.filter((x) => x === 1).length).toBe(2);
+    expect(result.filter((x) => x === 3).length).toBe(2);
+  });
+
+  test("each yielded step has required keys", () => {
+    const steps = collectAllSteps(bubbleSortGen([5, 1, 4, 2]));
+    steps.forEach((step) => {
+      expect(hasRequiredStepKeys(step)).toBe(true);
+    });
+  });
+
+  test("breaks early when no swaps occur (already sorted)", () => {
+    const steps = collectAllSteps(bubbleSortGen([1, 2, 3]));
+    const hasComparisons = steps.some((s) => s.comparisons > 0 || s.swaps > 0);
+    expect(hasComparisons).toBe(true);
+  });
+});
+
+// ── Selection Sort ───────────────────────────────────────────────────────────
+
+describe("selectionSortGen", () => {
+  test("sorts a simple array in ascending order", () => {
+    const result = getFinalArray(selectionSortGen([64, 25, 12, 22, 11]), [64, 25, 12, 22, 11]);
+    expect(result).toEqual([11, 12, 22, 25, 64]);
+  });
+
+  test("handles a single element", () => {
+    const result = getFinalArray(selectionSortGen([99]), [99]);
+    expect(result).toEqual([99]);
+  });
+
+  test("handles an empty array", () => {
+    const result = getFinalArray(selectionSortGen([]), []);
+    expect(result).toEqual([]);
+  });
+
+  test("handles reverse-sorted array", () => {
+    const result = getFinalArray(selectionSortGen([5, 4, 3, 2, 1]), [5, 4, 3, 2, 1]);
+    expect(result).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("each yielded step has required keys", () => {
+    const steps = collectAllSteps(selectionSortGen([5, 1, 4, 2]));
+    steps.forEach((step) => {
+      expect(hasRequiredStepKeys(step)).toBe(true);
+    });
+  });
+
+  test("currentIndices contains active index during iteration", () => {
+    const steps = collectAllSteps(selectionSortGen([5, 1, 4]));
+    const activeSteps = steps.filter((s) => s.currentIndices.active !== undefined);
+    expect(activeSteps.length).toBeGreaterThan(0);
+  });
+});
+
+// ── Insertion Sort ───────────────────────────────────────────────────────────
+
+describe("insertionSortGen", () => {
+  test("sorts a simple array in ascending order", () => {
+    const result = getFinalArray(insertionSortGen([12, 11, 13, 5, 6]), [12, 11, 13, 5, 6]);
+    expect(result).toEqual([5, 6, 11, 12, 13]);
+  });
+
+  test("handles a single element", () => {
+    const result = getFinalArray(insertionSortGen([42]), [42]);
+    expect(result).toEqual([42]);
+  });
+
+  test("handles an empty array", () => {
+    const result = getFinalArray(insertionSortGen([]), []);
+    expect(result).toEqual([]);
+  });
+
+  test("handles already-sorted array", () => {
+    const result = getFinalArray(insertionSortGen([1, 2, 3, 4]), [1, 2, 3, 4]);
+    expect(result).toEqual([1, 2, 3, 4]);
+  });
+
+  test("each yielded step has required keys", () => {
+    const steps = collectAllSteps(insertionSortGen([5, 1, 4, 2]));
+    steps.forEach((step) => {
+      expect(hasRequiredStepKeys(step)).toBe(true);
+    });
+  });
+
+  test("currentIndices contains key index when shifting", () => {
+    const steps = collectAllSteps(insertionSortGen([5, 1, 4, 2]));
+    const keySteps = steps.filter((s) => s.currentIndices.key !== undefined);
+    expect(keySteps.length).toBeGreaterThan(0);
+  });
+});
+
+// ── Merge Sort ──────────────────────────────────────────────────────────────
+
+describe("mergeSortGen", () => {
+  test("sorts a simple array in ascending order", () => {
+    const result = getFinalArray(mergeSortGen([38, 27, 43, 3, 9, 82, 10]), [38, 27, 43, 3, 9, 82, 10]);
+    expect(result).toEqual([3, 9, 10, 27, 38, 43, 82]);
+  });
+
+  test("handles a single element", () => {
+    const result = getFinalArray(mergeSortGen([7]), [7]);
+    expect(result).toEqual([7]);
+  });
+
+  test("handles an empty array", () => {
+    const result = getFinalArray(mergeSortGen([]), []);
+    expect(result).toEqual([]);
+  });
+
+  test("handles two elements", () => {
+    const result = getFinalArray(mergeSortGen([2, 1]), [2, 1]);
+    expect(result).toEqual([1, 2]);
+  });
+
+  test("handles duplicates", () => {
+    const result = getFinalArray(mergeSortGen([3, 3, 1, 2, 1]), [3, 3, 1, 2, 1]);
+    expect(isSorted(result)).toBe(true);
+    expect(result.filter((x) => x === 1).length).toBe(2);
+    expect(result.filter((x) => x === 3).length).toBe(2);
+  });
+
+  test("each yielded step has required keys and range in currentIndices", () => {
+    const steps = collectAllSteps(mergeSortGen([5, 1, 4, 2]));
+    steps.forEach((step) => {
+      expect(hasRequiredStepKeys(step)).toBe(true);
+    });
+    const rangeSteps = steps.filter((s) => s.currentIndices && s.currentIndices.range !== undefined);
+    expect(rangeSteps.length).toBeGreaterThan(0);
+  });
+});
+
+// ── Quick Sort ───────────────────────────────────────────────────────────────
+
+describe("quickSortGen", () => {
+  test("sorts a simple array in ascending order", () => {
+    const result = getFinalArray(quickSortGen([10, 7, 8, 9, 1, 5]), [10, 7, 8, 9, 1, 5]);
+    expect(result).toEqual([1, 5, 7, 8, 9, 10]);
+  });
+
+  test("handles a single element", () => {
+    const result = getFinalArray(quickSortGen([42]), [42]);
+    expect(result).toEqual([42]);
+  });
+
+  test("handles an empty array", () => {
+    const result = getFinalArray(quickSortGen([]), []);
+    expect(result).toEqual([]);
+  });
+
+  test("handles reverse-sorted array", () => {
+    const result = getFinalArray(quickSortGen([9, 8, 7, 6, 5]), [9, 8, 7, 6, 5]);
+    expect(result).toEqual([5, 6, 7, 8, 9]);
+  });
+
+  test("handles duplicates", () => {
+    const result = getFinalArray(quickSortGen([3, 1, 4, 1, 5, 9, 2, 6, 5]), [3, 1, 4, 1, 5, 9, 2, 6, 5]);
+    expect(isSorted(result)).toBe(true);
+  });
+
+  test("each yielded step has required keys with pivot info", () => {
+    const steps = collectAllSteps(quickSortGen([5, 1, 4, 2]));
+    steps.forEach((step) => {
+      expect(hasRequiredStepKeys(step)).toBe(true);
+    });
+    const pivotSteps = steps.filter((s) => s.currentIndices && s.currentIndices.pivot !== undefined);
+    expect(pivotSteps.length).toBeGreaterThan(0);
+  });
+});
+
+// ── Heap Sort ───────────────────────────────────────────────────────────────
+
+describe("heapSortGen", () => {
+  test("sorts a simple array in ascending order", () => {
+    const result = getFinalArray(heapSortGen([12, 11, 13, 5, 6, 7]), [12, 11, 13, 5, 6, 7]);
+    expect(result).toEqual([5, 6, 7, 11, 12, 13]);
+  });
+
+  test("handles a single element", () => {
+    const result = getFinalArray(heapSortGen([42]), [42]);
+    expect(result).toEqual([42]);
+  });
+
+  test("handles an empty array", () => {
+    const result = getFinalArray(heapSortGen([]), []);
+    expect(result).toEqual([]);
+  });
+
+  test("handles reverse-sorted array", () => {
+    const result = getFinalArray(heapSortGen([5, 4, 3, 2, 1]), [5, 4, 3, 2, 1]);
+    expect(result).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("handles duplicates", () => {
+    const result = getFinalArray(heapSortGen([3, 1, 4, 1, 5]), [3, 1, 4, 1, 5]);
+    expect(isSorted(result)).toBe(true);
+  });
+
+  test("each yielded step has required keys with heapSize info", () => {
+    const steps = collectAllSteps(heapSortGen([5, 1, 4, 2]));
+    steps.forEach((step) => {
+      expect(hasRequiredStepKeys(step)).toBe(true);
+    });
+    const heapSteps = steps.filter((s) => s.currentIndices && s.currentIndices.heapSize !== undefined);
+    expect(heapSteps.length).toBeGreaterThan(0);
+  });
+});