1 files changed, 53 insertions, 0 deletions
diff --git a/docs/dev/Testing.md b/docs/dev/Testing.md
new file mode 100644
index 000000000..40930f5d6
--- /dev/null
+++ b/docs/dev/Testing.md
@@ -0,0 +1,53 @@
+# Testing
+
+## Testing a new `zen` binary via ushell
+
+Both ushell commands that shell out to the `zen` CLI honor two environment variables. They let you drop a freshly built `zen` executable in front of ushell without touching the UE tree.
+
+### Affected commands
+
+- **`.zen`** — `status`, `start`, `stop`, `version`, `import-snapshot`, `create-workspace`, `create-share`, and any other `ZenUtilityBaseCmd`. Implemented in `channels/unreal/core/pylib/zen/cmd.py` (`ZenUtilityBaseCmd.get_zen_utility_command`, ~line 657).
+  - Note: `.zen start` and `.zen dashboard` launch `ZenLaunch` / `ZenDashboard` UE program targets from the engine tree — **those are not affected** by these variables. Only invocations of the `zen` utility itself are.
+- **`.getbuild`** — `channels/unreal/core/cmds/getbuild.py` (`GetBuild.run_zen`, ~line 365). Used for both the `builds list` query and the `builds download` step.
+
+### `UE_ZEN_BINARY_PATH`
+
+Absolute path to the `zen` executable to invoke.
+
+- **Default:** `<EngineDir>/Binaries/<HostPlatform>/zen[.exe]` from the active UE tree.
+- **When set:** the value is used verbatim — no platform folder, no `.exe` suffix added. Point it straight at your build output, e.g. `.../Zen/Source/Programs/Zen/out/build/x64-Debug/zen.exe`.
+- Both commands log `Using zen binary from UE_ZEN_BINARY_PATH: <path>` on each invocation, and raise `FileNotFoundError` if the file doesn't exist.
+
+### `UE_ZEN_ARGS`
+
+Extra global arguments prepended to every `zen` invocation.
+
+- Shell-split on whitespace (`str.split()`), then inserted **before** the subcommand args and before any user passthrough (`zenargs` / `runargs`).
+- Useful for things like `--log-level=debug`, custom config overrides, or experimental flags your new build understands.
+- Logged as `Using extra zen args from UE_ZEN_ARGS: <args>` when non-empty.
+
+### Typical workflow
+
+```bash
+# bash
+export UE_ZEN_BINARY_PATH=/path/to/new/zen.exe
+export UE_ZEN_ARGS="--log-level=debug"
+
+# PowerShell
+$env:UE_ZEN_BINARY_PATH = "C:\path\to\new\zen.exe"
+$env:UE_ZEN_ARGS        = "--log-level=debug"
+
+# cmd
+set UE_ZEN_BINARY_PATH=C:\path\to\new\zen.exe
+set UE_ZEN_ARGS=--log-level=debug
+```
+
+Then inside ushell:
+
+```
+.zen version        # confirms which binary is being invoked
+.zen status
+.getbuild win64 staged --match <cl>
+```
+
+Unset the variables (or open a fresh shell) to fall back to the in-tree `zen` shipped with the current UE sync.