sonamu 0.9.20 → 0.10.0

package/src/env.ts

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+
+import dotenv from "dotenv";
+
+export const SONAMU_ENVIRONMENTS = ["test", "development", "staging", "production"] as const;
+
+export type SonamuEnvironment = (typeof SONAMU_ENVIRONMENTS)[number];
+export type EnvironmentSnapshot = Record<string, string>;
+export type EnvironmentSnapshots = Record<SonamuEnvironment, EnvironmentSnapshot>;
+
+export function isSonamuEnvironment(value: string | undefined): value is SonamuEnvironment {
+  return SONAMU_ENVIRONMENTS.includes(value as SonamuEnvironment);
+}
+
+export function getSonamuEnvironment(env: NodeJS.ProcessEnv = process.env): SonamuEnvironment {
+  const nodeEnv = env.NODE_ENV;
+
+  if (nodeEnv === undefined || nodeEnv === "") {
+    return "development";
+  }
+
+  if (isSonamuEnvironment(nodeEnv)) {
+    return nodeEnv;
+  }
+
+  throw new Error(
+    `Invalid NODE_ENV "${nodeEnv}". Sonamu supports only ${SONAMU_ENVIRONMENTS.join(", ")}.`,
+  );
+}
+
+function readDotenvFile(filePath: string): EnvironmentSnapshot {
+  if (!existsSync(filePath)) {
+    return {};
+  }
+
+  return dotenv.parse(readFileSync(filePath));
+}
+
+function assertEnvironmentDotenvExists(rootPath: string, environment: SonamuEnvironment): void {
+  const commonEnvPath = path.join(rootPath, ".env");
+  const environmentEnvPath = path.join(rootPath, `.env.${environment}`);
+
+  if (!existsSync(commonEnvPath) && !existsSync(environmentEnvPath)) {
+    throw new Error(
+      `Missing Sonamu dotenv file. Create ${commonEnvPath} or ${environmentEnvPath}.`,
+    );
+  }
+}
+
+function removePreloadedCommonDotenvValues(
+  baseEnv: NodeJS.ProcessEnv,
+  commonEnv: EnvironmentSnapshot,
+  environmentEnv: EnvironmentSnapshot,
+): NodeJS.ProcessEnv {
+  const runtimeEnv = { ...baseEnv };
+
+  for (const [key, commonValue] of Object.entries(commonEnv)) {
+    if (environmentEnv[key] !== undefined && runtimeEnv[key] === commonValue) {
+      delete runtimeEnv[key];
+    }
+  }
+
+  return runtimeEnv;
+}
+
+export function readEnvironmentSnapshot(
+  rootPath: string,
+  environment: SonamuEnvironment,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): EnvironmentSnapshot {
+  assertEnvironmentDotenvExists(rootPath, environment);
+  const commonEnv = readDotenvFile(path.join(rootPath, ".env"));
+  const environmentEnv = readDotenvFile(path.join(rootPath, `.env.${environment}`));
+  const runtimeEnv = removePreloadedCommonDotenvValues(baseEnv, commonEnv, environmentEnv);
+
+  return {
+    ...commonEnv,
+    ...environmentEnv,
+    ...readDotenvFile(path.join(rootPath, ".env.local")),
+    ...runtimeEnv,
+    NODE_ENV: environment,
+  };
+}
+
+export function readAllEnvironmentSnapshots(
+  rootPath: string,
+  baseEnv: NodeJS.ProcessEnv = {},
+): EnvironmentSnapshots {
+  return Object.fromEntries(
+    SONAMU_ENVIRONMENTS.map((environment) => [
+      environment,
+      readEnvironmentSnapshot(rootPath, environment, baseEnv),
+    ]),
+  ) as EnvironmentSnapshots;
+}
+
+export function applyCurrentSnapshotToProcessEnv(rootPath: string): EnvironmentSnapshot {
+  const environment = getSonamuEnvironment();
+  const snapshot = readEnvironmentSnapshot(rootPath, environment);
+
+  for (const [key, value] of Object.entries(snapshot)) {
+    process.env[key] = value;
+  }
+
+  return snapshot;
+}
+
+export function isDevelopmentEnvironment(): boolean {
+  return getSonamuEnvironment() === "development";
+}
+
+export function isStagingEnvironment(): boolean {
+  return getSonamuEnvironment() === "staging";
+}
+
+export function isProductionEnvironment(): boolean {
+  return getSonamuEnvironment() === "production";
+}
+
+export function isTestEnvironment(): boolean {
+  return getSonamuEnvironment() === "test";
+}

package/src/migration/__tests__/migrator.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { type SonamuConfig } from "../../api/config";
+import { Sonamu } from "../../api/sonamu";
+import { type SonamuDBConfig, type SonamuDBPreset } from "../../database/db";
+import { setSDConfig } from "../../dict/sd";
+import { Migrator } from "../migrator";
+import { SlackConfirm } from "../slack-confirm";
+
+describe("Migrator environment target filtering", () => {
+  const originalEnv = { ...process.env };
+  const presets: SonamuDBPreset[] = [
+    "test",
+    "fixture",
+    "development",
+    "staging",
+    "production",
+    "test_readonly",
+    "development_readonly",
+    "staging_readonly",
+    "production_readonly",
+  ];
+
+  const dbConfig = Object.fromEntries(
+    presets.map((preset) => [
+      preset,
+      {
+        client: "postgresql",
+        connection: {
+          host: "localhost",
+          database: preset,
+        },
+      },
+    ]),
+  ) as SonamuDBConfig;
+
+  afterEach(() => {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in originalEnv)) {
+        delete process.env[key];
+      }
+    }
+    Object.assign(process.env, originalEnv);
+  });
+
+  const getMigrationTargetKeys = () => {
+    Sonamu.dbConfig = dbConfig;
+    return (
+      new Migrator() as unknown as {
+        getMigrationTargetKeys(): (keyof SonamuDBConfig)[];
+      }
+    ).getMigrationTargetKeys();
+  };
+
+  it("limits migration targets to production on a production server runtime", () => {
+    process.env.NODE_ENV = "production";
+
+    expect(getMigrationTargetKeys()).toEqual(["production"]);
+  });
+
+  it("keeps all writable targets available for local development UI workflows", () => {
+    process.env.NODE_ENV = "development";
+
+    expect(getMigrationTargetKeys()).toEqual([
+      "test",
+      "fixture",
+      "development",
+      "staging",
+      "production",
+    ]);
+  });
+});
+
+describe("SlackConfirm target validation", () => {
+  const presets: SonamuDBPreset[] = [
+    "test",
+    "fixture",
+    "development",
+    "staging",
+    "production",
+    "test_readonly",
+    "development_readonly",
+    "staging_readonly",
+    "production_readonly",
+  ];
+
+  const dbConfig = Object.fromEntries(
+    presets.map((preset) => [
+      preset,
+      {
+        client: "postgresql",
+        connection: {
+          host: "localhost",
+          database: preset,
+        },
+      },
+    ]),
+  ) as SonamuDBConfig;
+
+  const createConfig = (targets: string[]): SonamuConfig =>
+    ({
+      projectName: "sonamu-test",
+      api: {
+        dir: "src",
+        route: {
+          prefix: "/api",
+        },
+      },
+      i18n: {
+        defaultLocale: "ko",
+        supportedLocales: ["ko", "en"],
+      },
+      sync: {
+        targets: [],
+      },
+      database: {},
+      server: {},
+      apiConfig: {
+        contextProvider: (defaultContext) => defaultContext,
+        guardHandler: () => undefined,
+      },
+      slackConfirm: {
+        targets,
+        botToken: "xoxb-test",
+        channelId: "C123",
+      },
+    }) as SonamuConfig;
+
+  it("fails fast when slackConfirm.targets contains an unknown DB key", () => {
+    Sonamu.dbConfig = dbConfig;
+    Sonamu.config = createConfig(["production_old"]);
+    setSDConfig(Sonamu.config.i18n);
+
+    expect(() => new SlackConfirm().isTargetRequiresApproval("production")).toThrow(
+      /Slack Confirm targets/,
+    );
+  });
+
+  it("checks approval requirements only after configured targets match dbConfig keys", () => {
+    Sonamu.dbConfig = dbConfig;
+    Sonamu.config = createConfig(["production"]);
+    setSDConfig(Sonamu.config.i18n);
+
+    const slackConfirm = new SlackConfirm();
+
+    expect(slackConfirm.isTargetRequiresApproval("production")).toBe(true);
+    expect(slackConfirm.isTargetRequiresApproval("staging")).toBe(false);
+  });
+});

package/src/migration/migrator.ts

@@ -12,10 +12,11 @@ import { type SonamuDBConfig } from "../database/db";
 import { createKnexInstance } from "../database/knex";
 import { SD } from "../dict/sd";
 import { EntityManager } from "../entity/entity-manager";
+import { getSonamuEnvironment } from "../env";
 import { ServiceUnavailableException } from "../exceptions/so-exceptions";
 import { Naite } from "../naite/naite";
 import { type GenMigrationCode, type MigrationSet } from "../types/types";
-import { isTest } from "../utils/controller";
+import { isLocal, isTest } from "../utils/controller";
 import { exists } from "../utils/fs-utils";
 import { generateAlterCode, generateCreateCode } from "./code-generation";
 import { getMigrationSetFromEntity } from "./migration-set";
@@ -29,6 +30,32 @@ export type MigrationResult = {
 }[];
 
 export class Migrator {
+  private isMissingMigrationTableError(error: unknown): boolean {
+    if (typeof error !== "object" || error === null) {
+      return false;
+    }
+
+    const maybePostgresError = error as { code?: unknown; message?: unknown };
+    return (
+      maybePostgresError.code === "42P01" &&
+      typeof maybePostgresError.message === "string" &&
+      maybePostgresError.message.includes("knex_migrations")
+    );
+  }
+
+  private getMigrationTargetKeys(): (keyof SonamuDBConfig)[] {
+    const connKeys = Object.keys(Sonamu.dbConfig).filter(
+      (key) => !key.endsWith("_readonly"),
+    ) as (keyof SonamuDBConfig)[];
+
+    if (isLocal()) {
+      return connKeys;
+    }
+
+    const environment = getSonamuEnvironment();
+    return connKeys.filter((key) => key === environment);
+  }
+
   private async runMigrationsSequentially(
     conns: { connKey: keyof SonamuDBConfig; knex: Knex }[],
     action: "apply" | "rollback",
@@ -83,9 +110,7 @@ export class Migrator {
     const codes = await this.getMigrationCodes();
     Naite.t("migrator:getStatus:codes", codes);
 
-    const connKeys = Object.keys(Sonamu.dbConfig).filter(
-      (key) => !key.endsWith("_slave"),
-    ) as (keyof typeof Sonamu.dbConfig)[];
+    const connKeys = this.getMigrationTargetKeys();
 
     let migrationStatusError: string | undefined;
 
@@ -99,6 +124,10 @@ export class Migrator {
             try {
               return await tConn.migrate.status();
             } catch (err) {
+              if (this.isMissingMigrationTableError(err)) {
+                return codes.length;
+              }
+
               console.warn(
                 chalk.yellow(
                   `${connKey}의 마이그레이션 상태를 가져오는 데에 실패하였습니다. 데이터베이스가 올바르게 구성되지 않은 것 같습니다. 확인하시고 다시 시도해주세요.\n시도한 연결 설정:\n${JSON.stringify(knexOptions.connection, null, 2)}\n발생한 에러:\n${err}\n`,
@@ -113,6 +142,10 @@ export class Migrator {
               const [, fdList] = await tConn.migrate.list();
               return fdList.map((fd: { file: string }) => fd.file.replace(".ts", ""));
             } catch (err) {
+              if (this.isMissingMigrationTableError(err)) {
+                return codes.map((code) => code.name);
+              }
+
               migrationStatusError = err instanceof Error ? err.message : String(err);
               return [];
             }
@@ -121,6 +154,10 @@ export class Migrator {
             try {
               return await tConn.migrate.currentVersion();
             } catch (_err) {
+              if (this.isMissingMigrationTableError(_err)) {
+                return "none";
+              }
+
               migrationStatusError = _err instanceof Error ? _err.message : String(_err);
               return "error";
             }
@@ -130,7 +167,7 @@ export class Migrator {
           const connection = knexOptions.connection as Knex.PgConnectionConfig;
 
           return {
-            name: connKey.replace("_master", ""),
+            name: connKey,
             connKey,
             connString: `pg://${connection.user ?? ""}@${connection.host}:${
               connection.port
@@ -193,6 +230,14 @@ export class Migrator {
     Naite.t("migrator:runAction:action", action);
     Naite.t("migrator:runAction:targets", targets);
 
+    const allowedTargets = new Set(this.getMigrationTargetKeys());
+    const disallowedTargets = targets.filter((target) => !allowedTargets.has(target));
+    if (disallowedTargets.length > 0) {
+      throw new Error(
+        `Migration targets are not allowed in NODE_ENV=${getSonamuEnvironment()}: ${disallowedTargets.join(", ")}`,
+      );
+    }
+
     // get uniq knex configs
     const configs = unique(
       targets
@@ -359,9 +404,12 @@ export class Migrator {
     // 조인테이블 포함하여 MigrationSet 배열
     const entitySets: MigrationSet[] = [...entitySetsWithJoinTable, ...joinTables];
 
-    const codes: GenMigrationCode[] = (
-      await Promise.all(
-        entitySets.map(async (entitySet) => {
+    const codes: GenMigrationCode[] = [];
+    const batchSize = 4;
+
+    for (let i = 0; i < entitySets.length; i += batchSize) {
+      const batchCodes = await Promise.all(
+        entitySets.slice(i, i + batchSize).map(async (entitySet) => {
           const dbSet = await PostgreSQLSchemaReader.getMigrationSetFromDB(
             compareDB,
             entitySet.table,
@@ -377,8 +425,10 @@ export class Migrator {
             return await generateAlterCode(entitySet, dbSet, compareDB);
           }
         }),
-      )
-    ).flat();
+      );
+
+      codes.push(...batchCodes.flat());
+    }
 
     // normal 타입이 앞으로, foreign이 뒤로
     codes.sort((codeA, codeB) => {
@@ -402,20 +452,27 @@ export class Migrator {
    * @returns Shadow DB 테스트 결과
    */
   async runShadowTest(): Promise<MigrationResult> {
-    const tdbConn = Sonamu.dbConfig.test.connection as Knex.PgConnectionConfig;
-    const shadowDatabase = `${tdbConn.database}__migration_shadow`;
+    const baseTestConn = Sonamu.dbConfig.test.connection as Knex.PgConnectionConfig;
+    const workerId = process.env.SONAMU_WORKER_DB === "true" ? process.env.VITEST_POOL_ID : null;
+    const templateDatabase =
+      workerId !== null ? `${baseTestConn.database}_${workerId ?? "1"}` : baseTestConn.database;
+    const tdbConn = { ...baseTestConn, database: templateDatabase };
+    const shadowDatabase = `${templateDatabase}__migration_shadow`;
 
     // 테스트 상황에서는 트랜잭션을 초기화하고, 새 데이터베이스 커넥션을 가져와야 함
     if (isTest()) {
       await DB.clearTestTransaction();
-      // 병렬 테스트 모드에서는 worker DB 연결 유지
-      if (process.env.SONAMU_WORKER_DB !== "true") {
-        await DB.destroy();
-      }
+      await DB.destroy();
     }
 
     // 기존 Shadow DB 삭제 후 Shadow DB 생성
-    const tdb = createKnexInstance(Sonamu.dbConfig.test);
+    const tdb = createKnexInstance({
+      ...Sonamu.dbConfig.test,
+      connection: {
+        ...baseTestConn,
+        database: "postgres",
+      },
+    });
     try {
       !isTest() && console.log(chalk.magenta(`${shadowDatabase} 삭제`));
       await tdb.raw(`DROP DATABASE IF EXISTS ${shadowDatabase}`);

package/src/migration/slack-confirm.ts

@@ -25,10 +25,29 @@ export type SlackConfirmPendingResult = {
 export class SlackConfirm {
   private config = Sonamu.config.slackConfirm;
 
+  private validateConfiguredTargets(): void {
+    if (!this.config) {
+      return;
+    }
+
+    const validTargets = Object.keys(Sonamu.dbConfig);
+    const invalidTargets = this.config.targets.filter((target) => !validTargets.includes(target));
+
+    if (invalidTargets.length > 0) {
+      assert.fail(
+        SD("sonamu.error.slackConfirmInvalidTargets")(
+          invalidTargets.join(", "),
+          validTargets.join(", "),
+        ),
+      );
+    }
+  }
+
   /**
    * 설정이 있는지 확인합니다.
    */
   isConfigured(): boolean {
+    this.validateConfiguredTargets();
     return !!(this.config?.botToken && this.config?.channelId);
   }
 
@@ -36,6 +55,7 @@ export class SlackConfirm {
    * 해당 target이 승인 대상인지 확인합니다.
    */
   isTargetRequiresApproval(target: keyof SonamuDBConfig): boolean {
+    this.validateConfiguredTargets();
     return this.config?.targets?.includes(target) ?? false;
   }
 
@@ -98,6 +118,7 @@ export class SlackConfirm {
     requestor?: string,
   ): Promise<{ channel: string; ts: string }> {
     assert(this.config, SD("sonamu.error.slackConfirmNotConfigured"));
+    this.validateConfiguredTargets();
 
     const response = await fetch("https://slack.com/api/chat.postMessage", {
       method: "POST",

package/src/skills/sonamu/database.md

@@ -80,7 +80,7 @@ const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
 const generator = new FixtureGenerator(fixtureDb, fixtureDb, "fixture", EntityManager);
 
 // fixture fetch: production → fixture DB
-const sourceDb = DB.getDB("r"); // production_master
+const sourceDb = DB.getDB("r"); // current NODE_ENV readonly DB
 const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
 const generator = new FixtureGenerator(sourceDb, fixtureDb, "fixture", EntityManager);
 ```

package/src/skills/sonamu/testing-devrunner.md

@@ -343,7 +343,7 @@ export default defineConfig({
 
 ### Activation Conditions
 
-DevRunner is registered in `sonamu.ts` under the condition `isLocal() && config.test?.devRunner?.enabled`. `isLocal()` returns true when the `LR` environment variable is undefined or `"local"` (`controller.ts`). It only works in local development environments and is disabled in remote (production/staging) environments.
+DevRunner is registered in `sonamu.ts` under the condition `isLocal() && config.test?.devRunner?.enabled`. `isLocal()` returns true when `NODE_ENV` is `development` or `test` (`controller.ts`). It works in local development and test environments and is disabled in staging/production environments.
 
 ### Parallel Test DB Flow
 

package/src/stream/ws-telemetry-memory.ts

@@ -40,8 +40,8 @@ class InMemoryRingBuffer<TRecord extends { timestamp: number }> {
     this.capacity = options.maxRecords ?? DEFAULT_MAX_RECORDS;
     this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
     this.estimateBytes = estimateBytes;
-    this.slots = new Array(this.capacity);
-    this.slotBytes = new Array(this.capacity).fill(0);
+    this.slots = Array.from({ length: this.capacity });
+    this.slotBytes = Array.from({ length: this.capacity }, () => 0);
   }
 
   push(record: TRecord): void {

package/src/testing/fixture-generator.ts

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { type Knex } from "knex";
 
+import { type SonamuDBPreset } from "../database/db";
 import { type Entity } from "../entity/entity";
 import { type EntityManager } from "../entity/entity-manager";
 import { type EntityProp, type FixtureImportResult, type FixtureRecord } from "../types/types";
@@ -45,7 +46,7 @@ export class FixtureGenerator {
     // FixtureManager.insertFixtures가 dbName 문자열을 받기 때문에 직접 사용하지 않습니다
     // 미래 확장성을 위해 API 시그니처에는 포함시켰습니다
     _targetDb: Knex,
-    private targetDbName: "fixture" | "test" | "production_master",
+    private targetDbName: SonamuDBPreset,
     private entityManager: typeof EntityManager,
     options?: FixtureGeneratorOptions,
   ) {

package/src/testing/fixture-manager.ts

@@ -79,11 +79,11 @@ export class FixtureManagerClass {
     if (this._tdb !== null) {
       return;
     }
-    if (Sonamu.dbConfig.test && Sonamu.dbConfig.production_master) {
+    if (Sonamu.dbConfig.test && Sonamu.dbConfig.production) {
       const tConn = Sonamu.dbConfig.test.connection as Knex.ConnectionConfig & {
         port?: number;
       };
-      const pConn = Sonamu.dbConfig.production_master.connection as Knex.ConnectionConfig & {
+      const pConn = Sonamu.dbConfig.production.connection as Knex.ConnectionConfig & {
         port?: number;
       };
       if (
@@ -229,8 +229,7 @@ export class FixtureManagerClass {
 
     // 픽스쳐DB, 실DB
     const fixtureDatabase = (Sonamu.dbConfig.fixture.connection as Knex.ConnectionConfig).database;
-    const realDatabase = (Sonamu.dbConfig.production_master.connection as Knex.ConnectionConfig)
-      .database;
+    const realDatabase = (Sonamu.dbConfig.production.connection as Knex.ConnectionConfig).database;
 
     const selfQuery = `INSERT IGNORE INTO \`${fixtureDatabase}\`.\`${entity.table}\` (SELECT * FROM \`${realDatabase}\`.\`${entity.table}\` WHERE \`id\` = ${id})`;
 

package/src/testing/global-setup.ts

@@ -1,6 +1,19 @@
 import { loadConfig } from "../api/config";
+import { DB } from "../database/db";
 import { ParallelDBManager } from "./parallel-db-manager";
 
+function restoreProcessEnv(snapshot: NodeJS.ProcessEnv): void {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in snapshot)) {
+      delete process.env[key];
+    }
+  }
+
+  for (const [key, value] of Object.entries(snapshot)) {
+    process.env[key] = value;
+  }
+}
+
 /**
  * vitest globalSetup 함수를 생성합니다.
  * sonamu.config.ts의 test 설정을 읽어서 병렬 테스트 환경을 구성합니다.
@@ -22,30 +35,41 @@ export function createGlobalSetup() {
   return async function setup() {
     const { findApiRootPath } = await import("../utils/utils");
     const rootPath = findApiRootPath();
+    const envBeforeConfigLoad = { ...process.env };
     const config = await loadConfig(rootPath);
 
-    // 병렬 테스트가 비활성화된 경우 아무것도 하지 않음
-    if (!config.test?.parallel) {
-      return async function teardown() {
-        // no-op
-      };
-    }
+    try {
+      // 병렬 테스트가 비활성화된 경우 아무것도 하지 않음
+      if (!config.test?.parallel) {
+        return async function teardown() {
+          // no-op
+        };
+      }
 
-    const maxWorkers = config.test.maxWorkers ?? 4;
-    const templateDb = `${config.database.name}_test`;
+      const maxWorkers = config.test.maxWorkers ?? 4;
+      const dbConfig = DB.generateDBConfig(config.database, config.projectName);
+      const testConnection = dbConfig.test.connection;
+      const templateDb = (testConnection as { database: string }).database;
 
-    const connectionConfig = {
-      client: config.database.database ?? ("pg" as const),
-      connection:
-        config.database.environments?.test?.connection ?? config.database.defaultOptions.connection,
-    };
+      const adminConnection = {
+        ...(testConnection as Record<string, unknown>),
+        database: "postgres",
+      };
+
+      const connectionConfig = {
+        client: config.database.database ?? ("pg" as const),
+        connection: adminConnection,
+      };
 
-    const manager = new ParallelDBManager(maxWorkers, connectionConfig, templateDb);
-    await manager.createWorkerDatabases();
+      const manager = new ParallelDBManager(maxWorkers, connectionConfig, templateDb);
+      await manager.createWorkerDatabases();
 
-    return async function teardown() {
-      await manager.dropWorkerDatabases();
-    };
+      return async function teardown() {
+        await manager.dropWorkerDatabases();
+      };
+    } finally {
+      restoreProcessEnv(envBeforeConfigLoad);
+    }
   };
 }
 

package/src/testing/vitest-helpers.ts

@@ -4,6 +4,18 @@ import { loadConfig } from "../api/config";
 
 type VitestConfig = ViteUserConfig["test"];
 
+function restoreProcessEnv(snapshot: NodeJS.ProcessEnv): void {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in snapshot)) {
+      delete process.env[key];
+    }
+  }
+
+  for (const [key, value] of Object.entries(snapshot)) {
+    process.env[key] = value;
+  }
+}
+
 /**
  * sonamu.config.ts의 test 설정을 기반으로 vitest 테스트 설정을 반환합니다.
  *
@@ -22,7 +34,9 @@ type VitestConfig = ViteUserConfig["test"];
  */
 export async function getSonamuTestConfig(options?: VitestConfig): Promise<VitestConfig> {
   const { findApiRootPath } = await import("../utils/utils");
+  const envBeforeConfigLoad = { ...process.env };
   const config = await loadConfig(findApiRootPath());
+  restoreProcessEnv(envBeforeConfigLoad);
 
   const isParallel = config.test?.parallel ?? false;
   const maxWorkers = config.test?.maxWorkers ?? 4;