From 7ec1aa8c951b99a2c87a3879d7b4aae64943f943 Mon Sep 17 00:00:00 2001
From: robobun <robobun@oven.sh>
Date: Fri, 21 Nov 2025 12:45:57 -0800
Subject: [PATCH] docs: document new features from v1.3.2 and v1.3.3 (#24932)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## What does this PR do?

Adds missing documentation for features introduced in Bun v1.3.2 and
v1.3.3:

- **Standalone executable config flags**
(`docs/bundler/executables.mdx`): Document
`--no-compile-autoload-dotenv` and `--no-compile-autoload-bunfig` flags
that control automatic config file loading in compiled binaries
- **Test retry/repeats** (`docs/test/writing-tests.mdx`): Document the
`retry` and `repeats` test options for handling flaky tests
- **Disable env file loading**
(`docs/runtime/environment-variables.mdx`): Document `--no-env-file`
flag and `env = false` bunfig option

## How did you verify your code works?

- [x] Verified documentation is accurate against source code
implementation in `src/cli/Arguments.zig`
- [x] Verified features are not already documented elsewhere
- [x] Cross-referenced with v1.3.2 and v1.3.3 release notes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
---
 docs/bundler/executables.mdx           | 29 ++++++++++++++++++++
 docs/runtime/environment-variables.mdx | 17 ++++++++++++
 docs/test/writing-tests.mdx            | 37 ++++++++++++++++++++++++++
 3 files changed, 83 insertions(+)

diff --git a/docs/bundler/executables.mdx b/docs/bundler/executables.mdx
index 8de435e715..fefa2769e6 100644
--- a/docs/bundler/executables.mdx
+++ b/docs/bundler/executables.mdx
@@ -183,6 +183,35 @@ console.log(process.execArgv); // ["--smol", "--user-agent=MyBot"]
 
 ---
 
+## Disabling automatic config loading
+
+By default, standalone executables look for `.env` and `bunfig.toml` files in the directory where the executable is run. You can disable this behavior at build time for deterministic execution regardless of the user's working directory.
+
+```bash icon="terminal" terminal
+# Disable .env loading
+bun build --compile --no-compile-autoload-dotenv ./app.ts --outfile myapp
+
+# Disable bunfig.toml loading
+bun build --compile --no-compile-autoload-bunfig ./app.ts --outfile myapp
+
+# Disable both
+bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig ./app.ts --outfile myapp
+```
+
+You can also configure this via the JavaScript API:
+
+```ts
+await Bun.build({
+  entrypoints: ["./app.ts"],
+  compile: {
+    autoloadDotenv: false, // Disable .env loading
+    autoloadBunfig: false, // Disable bunfig.toml loading
+  },
+});
+```
+
+---
+
 ## Act as the Bun CLI
 
 <Note>New in Bun v1.2.16</Note>
diff --git a/docs/runtime/environment-variables.mdx b/docs/runtime/environment-variables.mdx
index c1b38edc1b..529b5348af 100644
--- a/docs/runtime/environment-variables.mdx
+++ b/docs/runtime/environment-variables.mdx
@@ -72,6 +72,23 @@ bun --env-file=.env.1 src/index.ts
 bun --env-file=.env.abc --env-file=.env.def run build
 ```
 
+## Disabling automatic `.env` loading
+
+Use `--no-env-file` to disable Bun's automatic `.env` file loading. This is useful in production environments or CI/CD pipelines where you want to rely solely on system environment variables.
+
+```sh
+bun run --no-env-file index.ts
+```
+
+This can also be configured in `bunfig.toml`:
+
+```toml bunfig.toml icon="settings"
+# Disable loading .env files
+env = false
+```
+
+Explicitly provided environment files via `--env-file` will still be loaded even when default loading is disabled.
+
 ---
 
 ## Quotation marks
diff --git a/docs/test/writing-tests.mdx b/docs/test/writing-tests.mdx
index a2de3839a5..5fee977356 100644
--- a/docs/test/writing-tests.mdx
+++ b/docs/test/writing-tests.mdx
@@ -78,6 +78,43 @@ In `bun:test`, test timeouts throw an uncatchable exception to force the test to
 
 The default timeout for each test is 5000ms (5 seconds) if not overridden by this timeout option or `jest.setDefaultTimeout()`.
 
+## Retries and Repeats
+
+### test.retry
+
+Use the `retry` option to automatically retry a test if it fails. The test passes if it succeeds within the specified number of attempts. This is useful for flaky tests that may fail intermittently.
+
+```ts title="example.test.ts" icon="/icons/typescript.svg"
+import { test } from "bun:test";
+
+test(
+  "flaky network request",
+  async () => {
+    const response = await fetch("https://example.com/api");
+    expect(response.ok).toBe(true);
+  },
+  { retry: 3 }, // Retry up to 3 times if the test fails
+);
+```
+
+### test.repeats
+
+Use the `repeats` option to run a test multiple times regardless of pass/fail status. The test fails if any iteration fails. This is useful for detecting flaky tests or stress testing. Note that `repeats: N` runs the test N+1 times total (1 initial run + N repeats).
+
+```ts title="example.test.ts" icon="/icons/typescript.svg"
+import { test } from "bun:test";
+
+test(
+  "ensure test is stable",
+  () => {
+    expect(Math.random()).toBeLessThan(1);
+  },
+  { repeats: 20 }, // Runs 21 times total (1 initial + 20 repeats)
+);
+```
+
+<Note>You cannot use both `retry` and `repeats` on the same test.</Note>
+
 ### 🧟 Zombie Process Killer
 
 When a test times out and processes spawned in the test via `Bun.spawn`, `Bun.spawnSync`, or `node:child_process` are not killed, they will be automatically killed and a message will be logged to the console. This prevents zombie processes from lingering in the background after timed-out tests.