From 49f9da14fe29cd0d8f5c0a812e7460e7baa91519 Mon Sep 17 00:00:00 2001
From: Bas Nijholt <bas@nijho.lt>
Date: Sun, 11 Jan 2026 21:57:52 +0100
Subject: [PATCH] docs: clarify Docker test setup requirements (#1383)

---
 Dockerfile      |  6 ++++--
 tests/README.md | 18 +++++++++++++++++-
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index c4d9c695..353a0748 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,8 +1,10 @@
 # See tests/README.md for instructions on how to run the tests.
 
 # tl;dr:
-# Run the following command in the adaptive-lighting repo folder to run the tests:
-# docker run -v $(pwd):/app basnijholt/adaptive-lighting:latest
+# 1. Clone HA core into ./core: git clone --depth 1 https://github.com/home-assistant/core.git core
+# 2. Setup symlinks: ./scripts/setup-symlinks
+# 3. Run tests (mount entire repo, not individual dirs, or symlinks break):
+#    docker run -v $(pwd):/app basnijholt/adaptive-lighting:latest
 
 # Optionally build the image yourself with:
 # docker build -t basnijholt/adaptive-lighting:latest .
diff --git a/tests/README.md b/tests/README.md
index a5b60839..3ccec21c 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -3,7 +3,23 @@
 To run the tests, check out the [CI configuration](../.github/workflows/pytest.yml) to see how they are executed in the CI pipeline.
 Alternatively, you can use the provided Docker image to run the tests locally or run them with VS Code directly in the dev container.
 
-To run the tests using the Docker image, navigate to the `adaptive-lighting` repo folder and execute the following command:
+## Prerequisites
+
+Before running tests with Docker, you need a local Home Assistant core checkout with symlinks:
+
+```bash
+# Clone HA core (one-time setup)
+git clone --depth 1 https://github.com/home-assistant/core.git core
+
+# Setup symlinks (one-time setup)
+./scripts/setup-symlinks
+```
+
+## Running tests with Docker
+
+Navigate to the `adaptive-lighting` repo folder and execute the following command.
+
+**Important:** Mount the entire repo (`-v $(pwd):/app`), not individual directories, or the symlinks will break.
 
 Linux / MacOS / Windows PowerShell:
 ```bash