From 02eda685b0b7fde6e481f289fa323634a89a47bc Mon Sep 17 00:00:00 2001
From: Richard Feldman <oss@rtfeldman.com>
Date: Wed, 17 Dec 2025 15:00:35 -0500
Subject: [PATCH] Update documentation for visual testing

---
 CONTRIBUTING.md                 |  2 +-
 docs/src/development/macos.md   | 29 +++++++++++++++++++++++++++++
 docs/src/development/windows.md |  2 ++
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f7aceadce18788ae2b8bb9d0fe4b5f16225e70d2..93c911dbfeddab8eb3e415b396ab65a9784e7b6f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,7 +44,7 @@ submitted. If you'd like your PR to have the best chance of being merged:
   effort. If there isn't already a GitHub issue for your feature with staff
   confirmation that we want it, start with a GitHub discussion rather than a PR.
 - Include a clear description of **what you're solving**, and why it's important.
-- Include **tests**.
+- Include **tests**. For UI changes, consider updating visual regression tests (see [Building Zed for macOS](./docs/src/development/macos.md#visual-regression-tests)).
 - If it changes the UI, attach **screenshots** or screen recordings.
 - Make the PR about **one thing only**, e.g. if it's a bugfix, don't add two
   features and a refactoring on top of that.
diff --git a/docs/src/development/macos.md b/docs/src/development/macos.md
index 9c99e5f8da62594c774e109e15f914788f51793d..13d5d105b269ef89feb13c4d8750e42ccbb79d42 100644
--- a/docs/src/development/macos.md
+++ b/docs/src/development/macos.md
@@ -57,6 +57,35 @@ And to run the tests:
 cargo test --workspace
 ```
 
+## Visual Regression Tests
+
+Zed includes visual regression tests that capture screenshots of real Zed windows and compare them against baseline images. These tests require macOS with Screen Recording permission.
+
+### Prerequisites
+
+You must grant Screen Recording permission to your terminal:
+
+1. Run the visual test runner once - macOS will prompt for permission
+2. Or manually: System Settings > Privacy & Security > Screen Recording
+3. Enable your terminal app (e.g., Terminal.app, iTerm2, Ghostty)
+4. Restart your terminal after granting permission
+
+### Running Visual Tests
+
+```sh
+cargo run -p zed --bin visual_test_runner --features visual-tests
+```
+
+### Updating Baselines
+
+When UI changes are intentional, update the baseline images:
+
+```sh
+UPDATE_BASELINE=1 cargo run -p zed --bin visual_test_runner --features visual-tests
+```
+
+Baseline images are stored in `crates/zed/test_fixtures/visual_tests/` and should be committed to the repository.
+
 ## Troubleshooting
 
 ### Error compiling metal shaders
diff --git a/docs/src/development/windows.md b/docs/src/development/windows.md
index 17382e0bee5b97c2ffc2d74794cf3881a3cb98a1..2f90beb05caeaca377293aa497fa8181c66d0dbd 100644
--- a/docs/src/development/windows.md
+++ b/docs/src/development/windows.md
@@ -112,6 +112,8 @@ And to run the tests:
 cargo test --workspace
 ```
 
+> **Note:** Visual regression tests are currently macOS-only and require Screen Recording permission. See [Building Zed for macOS](./macos.md#visual-regression-tests) for details.
+
 ## Installing from msys2
 
 Zed does not support unofficial MSYS2 Zed packages built for Mingw-w64. Please report any issues you may have with [mingw-w64-zed](https://packages.msys2.org/base/mingw-w64-zed) to [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed).