1 files changed, 83 insertions, 0 deletions
diff --git a/tests/README-DEBUG-TESTS.org b/tests/README-DEBUG-TESTS.org
new file mode 100644
index 0000000..ed303f8
--- /dev/null
+++ b/tests/README-DEBUG-TESTS.org
@@ -0,0 +1,83 @@
+#+TITLE: Wttrin Debug Integration Tests
+
+This directory contains integration tests with debug logging enabled.
+
+* Running the Tests
+
+#+begin_src bash
+cd /path/to/wttrin
+emacs --batch --eval "(progn
+  (package-initialize)
+  (add-to-list 'load-path \".\")
+  (setq wttrin-debug t)
+  (load-file \"wttrin.el\")
+  (load-file \"tests/test-integration-debug.el\")
+  (ert-run-tests-batch-and-exit))"
+#+end_src
+
+* What the Tests Show
+
+The integration tests demonstrate:
+
+1. *Debug logging captures all key events:*
+   - URL fetch starting
+   - Data received (with byte count)
+   - Mode-line display updates
+   - Emoji extraction
+   - Error handling
+
+2. *Example debug output from a successful fetch:*
+
+#+begin_example
+[wttrin-debug 11:51:46.490] mode-line-fetch: Starting fetch for Berkeley, CA
+[wttrin-debug 11:51:46.490] mode-line-fetch: URL = https://wttr.in/Berkeley%2C%20CA?m&format=%l:+%c+%t+%C
+[wttrin-debug 11:51:46.490] mode-line-fetch: Received data = "Berkeley, CA: ☀️ +62°F Clear"
+[wttrin-debug 11:51:46.490] mode-line-display: Updating display with: "Berkeley, CA: ☀️ +62°F Clear"
+[wttrin-debug 11:51:46.490] mode-line-display: Extracted emoji = "☀", font = Noto Color Emoji
+[wttrin-debug 11:51:46.490] mode-line-display: Complete. mode-line-string set = YES
+#+end_example
+
+* Using Debug Mode in Your Configuration
+
+** Enable Debug Before Loading
+
+#+begin_src emacs-lisp
+;; In your init.el, BEFORE (require 'wttrin):
+(setq wttrin-debug t)
+(require 'wttrin)
+#+end_src
+
+** Or Enable Later
+
+#+begin_src emacs-lisp
+M-x debug-wttrin-enable
+#+end_src
+
+** View Debug Log
+
+#+begin_src emacs-lisp
+M-x wttrin-debug-show-log
+#+end_src
+
+This opens a buffer showing all debug events with timestamps.
+
+** Clear Debug Log
+
+#+begin_src emacs-lisp
+M-x wttrin-debug-clear-log
+#+end_src
+
+* Test Fixtures
+
+- =fixtures/test-init.el= - Minimal init file with debug enabled for manual testing
+
+* Troubleshooting
+
+If wttrin isn't loading in your configuration:
+
+1. *Enable debug mode* (set =wttrin-debug= to =t= before loading)
+2. *Check dependencies:* Run =M-x package-list-packages= and ensure =xterm-color= is installed
+3. *View debug log:* Run =M-x wttrin-debug-show-log= after trying to use wttrin
+4. *Check for errors:* Look in =*Messages*= buffer for any error messages
+
+The debug log will show you exactly where the process stops or fails.