import { describe, expect, test } from "vitest"; import { envVariableDefinitions, getEnvVariableDefinition, getRequiredEnvVariableNames, groupEnvVariablesByClassification, listEnvVariables, validateEnv, } from "./index.js"; const EnvClassifications = [ "required-core", "required-per-app", "optional-provider", "local-development-only", "production-only", "deprecated-remove", ] as const; describe("listEnvVariables", () => { test("returns the full catalog when no filters are supplied", () => { expect(listEnvVariables()).toHaveLength(envVariableDefinitions.length); }); test("filters by classification", () => { const requiredCore = listEnvVariables({ classification: "required-core" }); expect(requiredCore.length).toBeGreaterThan(0); expect(requiredCore.every((definition) => definition.classification === "required-core")).toBe(true); expect(requiredCore.map((definition) => definition.name)).toContain("APP_NAME"); }); test("filters by runtime target", () => { const workerVars = listEnvVariables({ target: "worker" }); expect(workerVars.every((definition) => definition.targets.includes("worker"))).toBe(true); expect(workerVars.map((definition) => definition.name)).toContain("WORKER_ENABLED"); // PORT is web-only, so it must be excluded from the worker view. expect(workerVars.map((definition) => definition.name)).not.toContain("PORT"); }); test("combines classification and target filters", () => { const result = listEnvVariables({ classification: "required-core", target: "api" }); expect(result.every((definition) => definition.classification === "required-core" && definition.targets.includes("api"))).toBe(true); }); }); describe("getEnvVariableDefinition", () => { test("resolves an exact catalog match", () => { expect(getEnvVariableDefinition("APP_NAME")).toMatchObject({ name: "APP_NAME", classification: "required-core" }); }); test("resolves dynamic-prefix names to their wildcard definition", () => { expect(getEnvVariableDefinition("SITE_KEY_ACME")).toMatchObject({ name: "SITE_KEY_*", dynamicPrefix: "SITE_KEY_" }); }); test("returns undefined for unknown names", () => { expect(getEnvVariableDefinition("TOTALLY_UNKNOWN_VARIABLE")).toBeUndefined(); }); }); describe("groupEnvVariablesByClassification", () => { test("buckets every definition exactly once under all known classifications", () => { const groups = groupEnvVariablesByClassification(); expect(Object.keys(groups).sort()).toEqual([...EnvClassifications].sort()); const total = EnvClassifications.reduce((sum, classification) => sum + groups[classification].length, 0); expect(total).toBe(envVariableDefinitions.length); expect(groups["required-core"].map((definition) => definition.name)).toContain("APP_NAME"); expect(groups["optional-provider"].map((definition) => definition.name)).toContain("MAILJET_API_KEY"); }); }); describe("getRequiredEnvVariableNames", () => { test("requires only secrets without dev defaults for web in development", () => { expect(getRequiredEnvVariableNames()).toEqual(["API_ACCESS_TOKEN", "APP_NAME", "CRYPTO_SECRET", "DATABASE_URL", "JWT_SECRET", "SESSION_SECRET"]); }); test("promotes default-bearing required vars to mandatory in production", () => { const required = getRequiredEnvVariableNames({ nodeEnv: "production", target: "web" }); // APP_BASE_DOMAIN / WEB_APP_HOST carry dev defaults, so they are skipped in // development but become hard requirements once NODE_ENV is production. expect(required).toContain("APP_BASE_DOMAIN"); expect(required).toContain("WEB_APP_HOST"); expect(required).toContain("SESSION_SECRET"); }); test("pulls in optional providers only when explicitly requested", () => { const baseline = getRequiredEnvVariableNames({ target: "web" }); const withProviders = getRequiredEnvVariableNames({ target: "web", includeOptionalProviders: true }); expect(baseline).not.toContain("MAILJET_API_KEY"); expect(withProviders).toContain("MAILJET_API_KEY"); }); test("merges caller-supplied extraRequired names and returns a sorted unique list", () => { const required = getRequiredEnvVariableNames({ extraRequired: ["ZZZ_CUSTOM", "APP_NAME"] }); expect(required).toContain("ZZZ_CUSTOM"); // APP_NAME is already required and must not be duplicated. expect(required.filter((name) => name === "APP_NAME")).toHaveLength(1); expect([...required]).toEqual([...required].sort()); }); }); describe("validateEnv", () => { const WEB_DEV_REQUIRED = { APP_NAME: "HiveGrid", DATABASE_URL: "postgresql://user:pass@localhost:5432/app", SESSION_SECRET: "session-secret-value", CRYPTO_SECRET: "crypto-secret-value", API_ACCESS_TOKEN: "api-access-token-value", JWT_SECRET: "jwt-secret-value", }; test("reports each missing required variable with its catalog classification", () => { const result = validateEnv({}); expect(result.ok).toBe(false); expect(result.missing).toContainEqual({ name: "SESSION_SECRET", classification: "required-core", message: "SESSION_SECRET is required.", }); }); test("includes the target in the message when a target is provided", () => { const result = validateEnv({}, { target: "web" }); expect(result.missing).toContainEqual(expect.objectContaining({ name: "SESSION_SECRET", message: "SESSION_SECRET is required for web." })); }); test("passes once every required variable is present", () => { const result = validateEnv(WEB_DEV_REQUIRED); expect(result).toEqual({ ok: true, missing: [] }); }); test("never surfaces wildcard dynamic names as missing entries", () => { const result = validateEnv({}, { target: "api", includeOptionalProviders: true }); expect(result.missing.some((issue) => issue.name.includes("*"))).toBe(false); }); });