Miscellaneous improvements: testing, documentation, and code quality #11
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 29 commits
November 6, 2025 22:46
Added comprehensive Git Commit Guidelines section to CLAUDE.md including: - Atomic commit philosophy with pragmatic approach - Gitmoji convention table with 12 common emojis - Commit message format with confidence index in body (not title) - Examples at 3 confidence levels (omit for trivial, 85%, 70%) - Confidence index guidelines (95-100% to <50%) - Pragmatic grouping rules for commits - Note to keep commits tool-agnostic (no AI references) This helps maintain consistent, informative commit messages across the project. Confidence: 95%
Created organized task files to track project improvements: - README.md: Overview with 21 tasks across 4 categories - 01-documentation.md: 7 documentation alignment tasks (45min) - 02-critical-fixes.md: 5 urgent fixes including console.log, accessibility (30min) - 03-code-quality.md: 5 code quality improvements (60min) - 04-testing.md: 4 testing tasks for hooks and components (120min) Each task includes: - YAML frontmatter with metadata (priority, time, status) - Detailed problem description with file locations and line numbers - Step-by-step action items with code examples - Files to modify list - Why it's important explanation Total: 21 tasks, ~255 minutes of work identified. Confidence: 90%
- Remove debug console.log(style) from AssistantMessage code block renderer - Remove duplicate useEffect with empty deps in ChatContainer - Keep only the working scroll effect with proper dependencies ref: .claude/tasks/02-critical-fixes.md#task-1 ref: .claude/tasks/02-critical-fixes.md#task-2
Add try/catch wrapper with: - HTTP status validation (throw on !response.ok) - JSON parsing error handling - Response structure validation (check data.output exists and is string) - Better error messages for debugging This prevents app crashes on network errors and provides clear error feedback to users. Confidence: 85% ref: .claude/tasks/02-critical-fixes.md#task-3
Add aria-label attributes to: - Textarea: "Chat message input" - Submit button: "Send message" Ensures screen readers can identify these elements properly. Meets WCAG 2.1 Level A requirements. ref: .claude/tasks/02-critical-fixes.md#task-4 ref: .claude/tasks/02-critical-fixes.md#task-5
Skip "shows AI response after loading" test that expects 3 messages but gets 2. Documented in tasks for future investigation. The test may have been affected by webhook error handling changes. Needs deeper analysis to determine root cause. Confidence: 70% - requires investigation ref: .claude/tasks/04-testing.md#task-0
Update task files: - Mark all 5 critical fixes as completed in 02-critical-fixes.md - Add Task 0 in 04-testing.md to track failing test investigation - Update status, checklist items, and completion dates
Fixed the skipped test that was expecting an error response but the code was actually running in simulation mode and succeeding. The test now: - Properly mocks fetch to return a simulated response - Uses runAllTimersAsync to advance all timers (fetch + typing animation) - Verifies the AI response appears correctly Also updated the test setup to disable React Query retries for faster tests. ref: .claude/tasks/04-testing.md#task-0
Migrated from manual fetch mocking to MSW (Mock Service Worker) for more robust and maintainable HTTP mocking in tests. Changes: - Added msw as dev dependency - Created MSW handlers for webhook endpoints - Configured MSW server in test setup - Removed manual fetch stub from App.test.tsx - Used vi.stubEnv to set VITE_WEBHOOK_URL for tests Benefits: - More realistic network mocking at the network level - Better separation of concerns - Easier to add/modify API mocks - Consistent mocking across all tests All tests still passing ✅ Confidence: 95%
Added "Interaction Guidelines" section in CLAUDE.md to document when to use the AskUserQuestion tool. Clarifies that assumptions should be avoided and user clarification should be sought for ambiguous requirements, multiple implementation approaches, or architectural decisions.
Added 19 tests covering all functionality: - Success path with real webhook (3 tests) - Error handling for network/HTTP/malformed responses (5 tests) - Simulation mode with custom delays (3 tests) - Message state management and IDs (6 tests) - Loading and error states (2 tests) Tests use MSW for API mocking and follow best practices with toMatchObject for cleaner assertions. All tests pass successfully. ref: .claude/tasks/04-testing.md#task-1
Created .claude/guidelines/TESTING.md with best practices including: - One expect per logical entity using toMatchObject() - MSW for API mocking instead of direct fetch mocking - Test structure and organization patterns - Common patterns for hooks, components, and async operations - Coverage goals and anti-patterns to avoid Updated CLAUDE.md to reference the testing guidelines document.
Refactored tests to follow .claude/guidelines/TESTING.md principles: - Use single toMatchObject() per logical entity instead of multiple separate expects - Test complete state (messages + isLoading + isError) in one assertion - Use expect.arrayContaining() and expect.objectContaining() for flexible matching All 19 tests still pass. Improves readability and maintainability.
Added GIVEN-WHEN-THEN pattern as core principle #3 in testing guidelines: - Clear separation of test phases (Arrange-Act-Assert) - Self-documenting tests with explicit comments - Improved readability and maintainability Updated useChatWebhook tests to follow this pattern with examples showing: - GIVEN: Setup and preconditions - WHEN: Action being tested - THEN: Expected outcomes All 19 tests still pass.
Added 11 tests covering all hook functionality: - Basic functionality: progressive reveal, completion, onComplete callback (3 tests) - Speed and timing: charsPerTick and custom speed interval (2 tests) - Edge cases: empty text, text change mid-animation, cleanup on unmount (3 tests) - Progress calculation: percentage tracking (1 test) - State management: isTyping state and reset on text change (2 tests) All tests follow GIVEN-WHEN-THEN structure and use toMatchObject for assertions. Used vi.unmock() to test real implementation (hook is mocked globally in setup). ref: .claude/tasks/04-testing.md#task-2
Fixed 13 failing tests by properly handling fake timers and React Query: - Removed global fake timers that broke React Query mutations - Added fake timers only to simulation mode tests (which use setTimeout) - Used waitFor() for async state updates in webhook tests - Added delays to MSW responses to make loading states observable - Fixed unique ID test by advancing fake timer between messages All 19 tests now passing: - Real webhook tests (3/3) ✓ - Error handling tests (5/5) ✓ - Simulation mode tests (3/3) ✓ - Message state management tests (6/6) ✓ - Loading state tests (2/2) ✓ Confidence: 95% - all tests verified passing ref: .claude/tasks/04-testing.md#task-1
Created src/lib/constants.ts with documented constants:
- DEFAULT_INPUT_HEIGHT (64px)
- DEFAULT_SIMULATION_DELAY (1500ms)
- DEFAULT_TYPING_SPEED (10 chars/tick)
- USER_AVATAR_FALLBACK ("ME")
- TYPING_ANIMATION_INTERVAL (50ms)
Updated files to use constants:
- ChatContainer.tsx: inputHeight
- useChatWebhook.ts: simulationDelay
- useTypingText.ts: charsPerTick
- UserBubble.tsx: avatar fallback
Benefits:
- Self-documenting code with inline comments
- Single source of truth for magic numbers
- Easier to adjust values globally
- Better maintainability
All tests passing (45/45).
Confidence: 95%
ref: .claude/tasks/03-code-quality.md#task-1
Added to .claude/settings.local.json: - Bash(git restore:*) - allow git restore commands - Bash(cat:*) - allow cat commands for file inspection Added to .gitignore: - tsconfig.tsbuildinfo - TypeScript build cache file Build artifacts should not be versioned.
Added incrementing counter to generateMessageId() to prevent duplicate IDs when messages are created in the same millisecond (especially with fake timers in tests). Fixes React key warning. Confidence: 95% ref: .claude/tasks/04-testing.md#task-3
Added @testing-library/user-event@14.6.1 for more realistic user interaction simulation in tests (keyboard navigation, tab focus, etc.).
Task 3 - Improved test quality: - Replace fragile selectors (getByRole → getByTestId) - Add GIVEN-WHEN-THEN structure to all tests - Replace CSS selectors with test-ids - Add scroll behavior and empty state tests Task 4 - Added edge cases: - ChatInput: keyboard navigation (Tab), Enter submit, whitespace handling, ARIA labels - ChatContainer: 50+ messages, special characters (XSS/emoji/unicode), input height changes - App: rapid message submissions, button states, input clearing Improvements: - TypingIndicator: 1→2 tests - ChatInput: 6→10 tests - ChatContainer: 2→7 tests - App: 3→6 tests Confidence: 90% ref: .claude/tasks/04-testing.md#task-3 ref: .claude/tasks/04-testing.md#task-4
Created complete test suite with 8 tests covering: - Markdown rendering (bold, italic, headings, lists) - External link security (target="_blank", rel="noopener noreferrer") - Code blocks with syntax highlighting - Inline code rendering - Error message display with emoji prefix - Very long content handling - Multiple markdown elements in one message Confidence: 85% ref: .claude/tasks/04-testing.md#task-4
Fixed React hydration error where inline code used <div> inside <p>. Changed inline code to use <code> directly with Tailwind styles. Also removed unused destructured parameters (node, ref, style) from ReactMarkdown component handlers for cleaner code. Confidence: 95%
Fixed formatting issues caught by CI: - Added missing trailing comma in handlers.ts - Reformatted long lines in test files - Sorted imports in useChatWebhook.test.tsx
Fixed type incompatibility between react-syntax-highlighter and react-markdown by: - Using type assertion for oneDark style (known library type issue) - Excluding ref prop from being passed to SyntaxHighlighter - Properly handling ref only for inline code elements Confidence: 95%
Reorganized testing guidelines into 6 logical sections: 1. Testing Philosophy - fundamental "why" principles 2. Testing Standards - required tools and patterns 3. Best Practices - strategic guidelines 4. Technical Reference - tactical patterns and recipes 5. Anti-Patterns - organized by category 6. Resources - external links Key improvements: - Separated philosophical principles from technical practices - Moved MSW patterns to Technical Reference section - Reorganized Anti-Patterns by theme (Assertions, Mocking, Implementation) - Created clear progression: Why → What → How (strategic) → How (tactical) Confidence: 95%
Replaced .claude/settings.local.json with .claude/settings.json using wildcard patterns (e.g., "pnpm :*", "git :*") for cleaner permission management. Added explicit deny rules for destructive operations.
Require explicit confirmation before creating git commits.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR consolidates multiple improvements across testing, documentation, code quality, and accessibility:
Key Changes
Testing (4200+ lines of test coverage added)
useChatWebhook,useTypingTexthooksApp,ChatContainer,ChatInput,AssistantMessageDocumentation
.claude/guidelines/TESTING.md).claude/tasks/CLAUDE.mdwith workflow instructionsCode Quality
src/lib/constants.tsuseChatWebhookerror handling and validationAssistantMessageAccessibility
Test Plan
Stats