From 2d6c67ffc0883d1a300a18700fc087b86a11915e Mon Sep 17 00:00:00 2001
From: Alistair Smith <hi@alistair.sh>
Date: Mon, 25 Aug 2025 17:58:50 -0700
Subject: [PATCH] Clarify .env.local loading when NODE_ENV=test (#22139)

---
 docs/guides/runtime/set-env.md | 2 +-
 docs/runtime/env.md            | 4 ++++
 docs/test/runtime-behavior.md  | 2 ++
 3 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/guides/runtime/set-env.md b/docs/guides/runtime/set-env.md
index 513eb9793a..cac8935b1d 100644
--- a/docs/guides/runtime/set-env.md
+++ b/docs/guides/runtime/set-env.md
@@ -17,7 +17,7 @@ Bun reads the following files automatically (listed in order of increasing prece
 
 - `.env`
 - `.env.production`, `.env.development`, `.env.test` (depending on value of `NODE_ENV`)
-- `.env.local`
+- `.env.local` (not loaded when `NODE_ENV=test`)
 
 ```txt#.env
 FOO=hello
diff --git a/docs/runtime/env.md b/docs/runtime/env.md
index bf06d0ceec..17df54315f 100644
--- a/docs/runtime/env.md
+++ b/docs/runtime/env.md
@@ -8,6 +8,10 @@ Bun reads the following files automatically (listed in order of increasing prece
 - `.env.production`, `.env.development`, `.env.test` (depending on value of `NODE_ENV`)
 - `.env.local`
 
+{% callout %}
+**Note:** When `NODE_ENV=test`, `.env.local` is **not** loaded. This ensures consistent test environments across different executions by preventing local overrides during testing. This behavior matches popular frameworks like [Next.js](https://nextjs.org/docs/pages/guides/environment-variables#test-environment-variables) and [Create React App](https://create-react-app.dev/docs/adding-custom-environment-variables/#what-other-env-files-can-be-used).
+{% /callout %}
+
 ```txt#.env
 FOO=hello
 BAR=world
diff --git a/docs/test/runtime-behavior.md b/docs/test/runtime-behavior.md
index 56ae6bf5de..5c51e06063 100644
--- a/docs/test/runtime-behavior.md
+++ b/docs/test/runtime-behavior.md
@@ -12,6 +12,8 @@ test("NODE_ENV is set to test", () => {
 });
 ```
 
+When `NODE_ENV` is set to `"test"`, Bun will not load `.env.local` files. This ensures consistent test environments across different executions by preventing local overrides during testing. Instead, use `.env.test` for test-specific environment variables, which should be committed to your repository for consistency across all developers and CI environments.
+
 #### `$TZ` environment variable
 
 By default, all `bun test` runs use UTC (`Etc/UTC`) as the time zone unless overridden by the `TZ` environment variable. This ensures consistent date and time behavior across different development environments.