diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | docs/NOTES.org | 131 | ||||
| -rw-r--r-- | docs/session-1-summary.org | 141 | ||||
| -rw-r--r-- | docs/testing-plan.org | 152 |
4 files changed, 1 insertions, 424 deletions
@@ -1 +1,2 @@ /todo.org +/docs/ diff --git a/docs/NOTES.org b/docs/NOTES.org deleted file mode 100644 index 7040321..0000000 --- a/docs/NOTES.org +++ /dev/null @@ -1,131 +0,0 @@ - -* Claude Code Session Notes -This file contains important information for Claude to remember between sessions. -** User Information -*** Calendar Location -Craig's calendar is available at: =/home/cjennings/sync/org/gcal.org= - -Use this to: -- Check meeting times and schedules -- Verify when events occurred -- See what's upcoming - -*** Todo List Location -Craig's todo list is at: =/home/cjennings/code/wttrin/todo.org= - -*IMPORTANT*: When Craig refers to "my todo list" or "task list", he means this file. -- Use the Edit tool to update tasks in this file -- Do NOT confuse this with Claude Code's TodoWrite tool (which is for tracking Claude's internal task progress) -- This is an org-mode file with TODO/DOING/DONE states - -*** Quality Engineering Guidelines -Craig's quality engineering and testing practices are documented at: -=/home/cjennings/.emacs.d/ai-prompts/quality-engineer.org= - -*Key principles for wttrin testing project:* -- Follow ERT (Emacs Lisp Regression Testing) framework -- Separate interactive UI from logic (Interactive vs Non-Interactive Pattern) - - Internal functions prefixed with =--= contain pure logic - - Interactive wrappers handle user prompts - - Test the internal functions with direct parameters -- Test file organization: - - Unit tests: =test-wttrin-<methodname>.el= (one file per method) - - Integration tests: =test-integration-<area-or-workflow>.el= - - Test utilities: =testutil-<category>.el= -- Test naming: =test-<module>-<function>-<category>-<scenario>-<expected-result>= - - Categories: normal, boundary, error -- NEVER hardcode dates in tests - use dynamic timestamp generation -- DON'T MOCK WHAT YOU'RE TESTING - only mock external dependencies -- Each test must be independent and deterministic - -*Current testing project:* -- Adding comprehensive ERT tests to wttrin package -- Multi-session project - track progress in session notes -- Refactor functions to be testable (separate UI from logic) -- Goal: Full test coverage for all core functionality - -*Session 1 Progress (2025-11-03):* -- Created comprehensive testing plan in =docs/testing-plan.org= -- Refactored wttrin.el to separate UI from logic - - Extracted =wttrin--build-url= (pure function for URL building) - - Fixed multiple bugs in =wttrin-fetch-raw-string=: - - Removed incorrect callback parameter to url-retrieve-synchronously - - Added nil buffer check for network failures - - Strip HTTP headers before decoding - - Kill buffer after use to prevent leaks - - URL encoding now handled properly - - Fixed double concatenation bug in =wttrin--get-cached-or-fetch= - - Fixed nil handling in =wttrin-additional-url-params= -- Created test infrastructure: - - =tests/testutil-wttrin.el= with test utilities and helpers - - 4 unit test files with 33 comprehensive tests -- Test Results: *33 tests, 33 passing, 0 failures* - -*Files with test coverage:* -1. =wttrin-additional-url-params= - 7 tests (normal, boundary, error cases) -2. =wttrin--make-cache-key= - 9 tests (includes Unicode, special chars) -3. =wttrin--build-url= - 10 tests (URL encoding, parameters) -4. =wttrin--cleanup-cache-if-needed= - 7 tests (cache eviction logic) - -*Next session priorities:* -1. Write tests for =wttrin--get-cached-or-fetch= (cache workflow) -2. Extract parsing logic from =wttrin-query= and test it -3. Write integration tests for fetch → parse → display workflow -4. Test error handling paths -5. Consider adding tests for interactive functions (if needed) - -*** Working Style -- Craig uses Emacs as primary tool -** Session Protocols / Vocabulary -*** "Add to our vocabulary" -When Craig says "let's add this to our vocabulary" or a similar phrase, you should execute this sequence: - -1. Add a row at this level to the parent org heading named "Session Protocols / Vocabulary" -2. Ask Craig for any similar names he might use. -3. If he already hasn't provided this information or it isn't clear, ask him for the steps you should take when you see this phrase. Make sure the phrase under discussion is clear. -4. Write the definition in steps just like any of the other org-headers and their content in this list. -5. Then remember the instructions, because he's likely to ask you to do that vocabulary word. -*** "Let's wrap it up" / "That's a wrap" - End of Session Routine -When Craig says "let's wrap it up" or "that's a wrap", execute this sequence: - -1. *Update notes*: Add anything important to remember for next session to this file (CLAUDE-NOTES.org) - - Session summary if significant work was done - - Critical reminders for tomorrow - - Any new conventions or preferences learned - -2. *Git commit and push*: Commit all changes in the repository and push to remote - - Use descriptive commit message - - Ensure working tree is clean - - Confirm push succeeded - -3. *Final exchange*: Brief valediction/good wishes before Craig closes laptop - - Keep it warm but concise - - Acknowledge the day's work if appropriate - - "Good night" / "Talk tomorrow" / similar - -This ensures clean handoff between sessions and nothing gets lost. - -** File Naming Conventions -*** Update todo.org Links When Renaming Files -Many documents in this project are linked in =todo.org= using org-mode =file:= links. - -*When renaming ANY file*, always search =todo.org= for references to that file and update all links to the new filename. - -Example workflow: -1. Rename file (e.g., add =TOOLARGE-= prefix) -2. Search =todo.org= for old filename -3. Update all =file:= links to new filename - -This prevents broken links and maintains the integrity of the project documentation. - -** File Format Preferences -*** ALWAYS Use Org-Mode Format -The user uses Emacs as their primary tool. *ALWAYS* create new documentation files in =.org= format, not =.md= (markdown). - -*Rationale*: -- Org-mode files are well-supported in Emacs -- Can be easily exported to any other format (HTML, PDF, Markdown, etc.) -- Better integration with user's workflow - -*Exception*: Only use .md if specifically requested or if the file is intended for GitHub/web display where markdown is expected. - diff --git a/docs/session-1-summary.org b/docs/session-1-summary.org deleted file mode 100644 index ebb0f4c..0000000 --- a/docs/session-1-summary.org +++ /dev/null @@ -1,141 +0,0 @@ -* WTTRIN Testing Project - Session 1 Summary -Date: 2025-11-03 -Status: ✅ Complete - -** What Was Accomplished - -*** Bug Fixes in wttrin.el (5 bugs fixed) -1. ✅ Fixed =wttrin-additional-url-params= to handle nil properly -2. ✅ Removed incorrect callback parameter in =wttrin-fetch-raw-string= -3. ✅ Added nil buffer check for network failures -4. ✅ Strip HTTP headers before decoding (was causing display issues) -5. ✅ Kill buffer after fetch to prevent memory leaks -6. ✅ Fixed double concatenation of URL params in cache function -7. ✅ Added proper URL encoding via new =wttrin--build-url= function - -*** Code Refactoring -- Extracted =wttrin--build-url= as pure function (testable) -- Separated URL building logic from network I/O -- All refactoring maintains backward compatibility - -*** Test Infrastructure Created -- =tests/testutil-wttrin.el= - Shared test utilities - - Cache helpers (add, clear, size) - - Custom variable management macros - - Setup/teardown functions - -*** Test Coverage Added -*Total: 33 tests, 100% passing* - -1. *test-wttrin-additional-url-params.el* (7 tests) - - Normal: metric, USCS, wind speed units - - Boundary: nil, empty string, single char - - Error: invalid type handling - -2. *test-wttrin--make-cache-key.el* (9 tests) - - Normal: location with different unit systems - - Boundary: empty string, spaces, commas, Unicode, special chars - - Error: nil location - -3. *test-wttrin--build-url.el* (10 tests) - - Normal: simple locations, different unit systems - - Boundary: spaces, commas, special chars, Unicode, GPS coords - - Error: nil location signals error - -4. *test-wttrin--cleanup-cache-if-needed.el* (7 tests) - - Normal: cache cleanup when exceeding max size - - Boundary: empty cache, exactly at max, edge cases - - Validates oldest entries are removed correctly - -** Test Execution -All tests pass successfully: - -#+begin_src shell -emacs --batch -L . -L tests \ - --eval "(setq package-user-dir \"~/.emacs.d/elpa\")" \ - --eval "(package-initialize)" \ - -l wttrin.el -l testutil-wttrin.el \ - -l test-wttrin-additional-url-params.el \ - -l test-wttrin--make-cache-key.el \ - -l test-wttrin--build-url.el \ - -l test-wttrin--cleanup-cache-if-needed.el \ - -f ert-run-tests-batch-and-exit -#+end_src - -*Result:* Running 33 tests ... Ran 33 tests, 33 results as expected, 0 unexpected - -** Documentation Created -- =docs/testing-plan.org= - Comprehensive testing roadmap - - Identifies all functions needing tests - - Categorizes by refactoring needs - - Phases for implementation - - Estimated 95 total tests when complete - -- =docs/NOTES.org= - Updated with: - - Quality engineering guidelines reference - - Session 1 progress summary - - Next session priorities - -- =docs/session-1-summary.org= - This file! - -** Files Modified -- =wttrin.el= - Bug fixes and refactoring -- =docs/NOTES.org= - Testing project notes added -- =~/.claude/settings.json= - Added wttrin project permissions - -** Files Created -- =docs/testing-plan.org= -- =docs/bugs.org= -- =tests/testutil-wttrin.el= -- =tests/test-wttrin-additional-url-params.el= -- =tests/test-wttrin--make-cache-key.el= -- =tests/test-wttrin--build-url.el= -- =tests/test-wttrin--cleanup-cache-if-needed.el= -- =docs/session-1-summary.org= - -** Next Session Priorities -1. Write tests for =wttrin--get-cached-or-fetch= (cache workflow with TTL) -2. Extract and test parsing logic from =wttrin-query= -3. Write integration tests for fetch → parse → display workflow -4. Test error handling paths throughout -5. Consider async loading tests (if needed) - -** Progress Metrics -- Functions tested: 4 of ~10 planned -- Test coverage: ~40% of core functions -- Bugs fixed: 7 (from original audit) -- Bugs remaining: ~9 (see =docs/bugs.org= and =todo.org=) -- Tests written: 33 -- Tests passing: 33 (100%) -- Tests failing: 0 - -** Notes for Next Session -- Test utilities are working well - easy to add new tests -- Refactoring pattern (extract pure functions) is effective -- Cache logic is more complex - needs careful testing -- Consider mocking url-retrieve-synchronously for fetch tests -- Buffer manipulation in wttrin-query needs extraction for testing - -** How to Run Tests -Individual test file: -#+begin_src shell -emacs --batch -L . -L tests \ - --eval "(setq package-user-dir \"~/.emacs.d/elpa\")" \ - --eval "(package-initialize)" \ - -l wttrin.el -l testutil-wttrin.el \ - -l test-wttrin-<function-name>.el \ - -f ert-run-tests-batch-and-exit -#+end_src - -All tests: -#+begin_src shell -emacs --batch -L . -L tests \ - --eval "(setq package-user-dir \"~/.emacs.d/elpa\")" \ - --eval "(package-initialize)" \ - -l wttrin.el -l testutil-wttrin.el \ - -l test-wttrin-additional-url-params.el \ - -l test-wttrin--make-cache-key.el \ - -l test-wttrin--build-url.el \ - -l test-wttrin--cleanup-cache-if-needed.el \ - -f ert-run-tests-batch-and-exit -#+end_src diff --git a/docs/testing-plan.org b/docs/testing-plan.org deleted file mode 100644 index e2fae9a..0000000 --- a/docs/testing-plan.org +++ /dev/null @@ -1,152 +0,0 @@ -* WTTRIN Testing Plan - -** Methods Analysis - -*** Pure Logic Functions (Easy to Test - No Refactoring Needed) -These functions have no side effects and can be tested directly: - -**** =wttrin-additional-url-params= (Line 103) -- *Purpose*: Concatenates unit system into URL parameter -- *Current issues*: Has a bug (returns "?" when wttrin-unit-system is nil) -- *Test categories*: - - Normal: wttrin-unit-system = "m", should return "?m" - - Normal: wttrin-unit-system = "u", should return "?u" - - Boundary: wttrin-unit-system = nil, currently returns "?" (bug!) - - Boundary: wttrin-unit-system = "", should return "?" - - Error: wttrin-unit-system is number/list (type error) - -**** =wttrin--make-cache-key= (Line 183) -- *Purpose*: Creates cache key from location and settings -- *Test categories*: - - Normal: location + unit system, returns "location|m" - - Normal: location with no unit system, returns "location|default" - - Boundary: Empty location string - - Boundary: Location with special characters (spaces, commas, Unicode) - - Error: nil location - -**** =wttrin--cleanup-cache-if-needed= (Line 217) -- *Purpose*: Removes oldest 20% of cache entries when cache exceeds max size -- *Test categories*: - - Normal: Cache at max, removes correct number of oldest entries - - Normal: Cache under max, does nothing - - Boundary: Cache exactly at max limit - - Boundary: Empty cache - - Boundary: Cache with 1 entry at max=1 - -*** Functions Needing Refactoring (Mixed Logic + Side Effects) - -**** =wttrin-fetch-raw-string= (Line 107) -*Current state*: Mixes URL building, network I/O, and decoding - -*Refactoring plan*: -- Create =wttrin--build-url= (pure): Takes query, returns URL string -- Create =wttrin--fetch-url= (I/O): Takes URL, returns raw response -- Keep =wttrin-fetch-raw-string= as thin wrapper calling both - -*Tests for =wttrin--build-url=*: -- Normal: query "Paris" → "https://wttr.in/Paris?A" -- Normal: query with unit system "m" → "https://wttr.in/Paris?mA" -- Boundary: query with spaces "New York" → properly encoded URL -- Boundary: query with special chars ",./~" → properly encoded -- Boundary: Empty query → "https://wttr.in/?A" -- Error: nil query → error - -*Tests for =wttrin--fetch-url=*: -- Mock url-retrieve-synchronously -- Normal: successful fetch returns buffer content -- Error: nil buffer (network failure) → error -- Error: HTTP error codes (404, 500) → error - -**** =wttrin-query= (Line 133) -*Current state*: Mixes data fetching, parsing, buffer creation, display, keymaps - -*Refactoring plan*: -- Create =wttrin--parse-weather-data= (pure): Takes raw string, returns structured data -- Create =wttrin--format-weather-buffer= (pure): Takes structured data, returns formatted string -- Keep =wttrin-query= for buffer/display/keymap setup - -*Tests for =wttrin--parse-weather-data=*: -- Normal: Valid weather data → parsed location, timestamp, body -- Boundary: Minimal valid data -- Error: "ERROR" in response → returns nil or signals error -- Error: Malformed data → handles gracefully - -*Tests for =wttrin--format-weather-buffer=*: -- Normal: Formatted data with location, timestamp, weather -- Boundary: Empty weather body -- Boundary: Very long weather data - -*** Cache Functions (Testable with Mocking) - -**** =wttrin--get-cached-or-fetch= (Line 187) -*Test categories*: -- Normal: Cache hit with fresh data → returns cached data -- Normal: Cache miss → fetches new data and caches it -- Normal: Cache hit with stale data → fetches new data -- Boundary: Force refresh bypasses cache -- Error: Fetch fails, cached data available → returns stale cache -- Error: Fetch fails, no cached data → propagates error - -*** Interactive Functions (Minimal Testing Needed) -These are thin wrappers around logic - test the logic, not the UI: - -- =wttrin= (Line 251) - Just calls wttrin-query with completing-read result -- =wttrin-exit= (Line 117) - Just calls quit-window -- =wttrin-requery= (Line 122) - Just prompts and calls wttrin-query -- =wttrin-requery-force= (Line 240) - Sets flag and calls wttrin-query -- =wttrin-clear-cache= (Line 231) - Just calls clrhash - -** Test File Structure - -Following the quality-engineer.org guidelines: - -*** Unit Test Files (tests/ directory) -- =test-wttrin-additional-url-params.el= -- =test-wttrin--make-cache-key.el= -- =test-wttrin--cleanup-cache-if-needed.el= -- =test-wttrin--build-url.el= (after refactoring) -- =test-wttrin--parse-weather-data.el= (after refactoring) -- =test-wttrin--format-weather-buffer.el= (after refactoring) -- =test-wttrin--get-cached-or-fetch.el= - -*** Integration Test Files -- =test-integration-wttrin-cache-workflow.el= (cache hit/miss/refresh) -- =test-integration-wttrin-fetch-display.el= (fetch → parse → display) - -*** Test Utilities -- =testutil-wttrin.el= (shared test helpers) - -** Refactoring Priority - -*** Phase 1: Test Pure Functions (No Refactoring Needed) -1. =wttrin-additional-url-params= -2. =wttrin--make-cache-key= -3. =wttrin--cleanup-cache-if-needed= - -*** Phase 2: Refactor and Test URL Building -1. Extract =wttrin--build-url= from =wttrin-fetch-raw-string= -2. Write tests for =wttrin--build-url= -3. Extract =wttrin--fetch-url= (I/O portion) -4. Write tests for =wttrin--fetch-url= (mocked) - -*** Phase 3: Refactor and Test Query Logic -1. Extract =wttrin--parse-weather-data= -2. Write tests for parsing -3. Extract =wttrin--format-weather-buffer= -4. Write tests for formatting - -*** Phase 4: Integration Tests -1. Cache workflow tests -2. Fetch-to-display workflow tests - -** Estimated Test Count -- Pure functions: ~30 tests -- Refactored functions: ~40 tests -- Cache logic: ~15 tests -- Integration: ~10 tests -*Total*: ~95 tests - -** Session Progress Tracking -- Session 1 (2025-11-03): Created testing plan, identified functions -- Session 2: TBD - Start with Phase 1 -- Session 3+: Continue through phases |