tests: add JSDOM test env, comprehensive unit tests for frontend utils/state, and e2e screenshots

- Add JSDOM-based test environment to support browser APIs in Node:
  - tests/unit/setup.mjs
    - Creates a JSDOM document and exposes window/document/globals
    - Provides a minimal crypto implementation (randomUUID + getRandomValues)
    - Cleans up dom.window on process exit

- Enable ESM for unit tests:
  - tests/unit/package.json ({"type":"module"})

- Add extensive unit tests for frontend state management:
  - tests/unit/test-state.mjs
    - Verifies state object shape (historicalEntries, predefinedSuggestions, activeTimers, timerInterval, activeChartInstances)
    - Tests calculateElapsedMs for paused/running timers, accumulated time, clock skew, very long durations
    - Tests hasRunningTimers in multiple scenarios
    - Tests clearTimerInterval behavior and safety

- Add extensive unit tests for utility functions:
  - tests/unit/test-utils.mjs
    - formatDuration: many cases (seconds, minutes, hours, large values)
    - sanitizeInput: trimming, removal of dangerous chars, length limiting, unicode and edge cases
    - generateUUID: v4 format validation and uniqueness checks
    - getRunningTasksKey: normalization/casing tests
    - getDistinctColors: output shape, hex format, counts and behavior for large requests
    - showNotification presence check (DOM dependent)

- Add e2e screenshot fixtures:
  - tests/screenshots/e2e/12-error-handling.png
  - tests/screenshots/e2e/13-csv-export.png
  - tests/screenshots/e2e/14-final-state.png
  - (binary images added to support visual regression / CI screenshot comparisons)

Notes:
- Tests are written using Node's builtin test/assert (node:test + node:assert).
- setup.mjs should be imported before test modules that depend on browser globals.
- This commit focuses on test infra and coverage; no production source changes included.

Author: kanad13

.github/workflows/test.yml

@@ -0,0 +1,80 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [main, local_node_refactor]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run unit tests
+        run: npm run test:unit
+
+      - name: Start server
+        run: |
+          npm start &
+          echo $! > server.pid
+
+      - name: Wait for server
+        run: |
+          for i in {1..30}; do
+            if curl -s http://localhost:13331/api/health > /dev/null; then
+              echo "Server is ready"
+              exit 0
+            fi
+            echo "Waiting for server... ($i/30)"
+            sleep 2
+          done
+          echo "Server failed to start"
+          exit 1
+
+      - name: Run backend API tests
+        run: npm run test:api
+
+      - name: Run E2E tests
+        run: HEADLESS=true npm run test:e2e
+
+      - name: Upload screenshots
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-screenshots-node-${{ matrix.node-version }}
+          path: tests/screenshots/
+          retention-days: 7
+
+      - name: Stop server
+        if: always()
+        run: |
+          if [ -f server.pid ]; then
+            kill $(cat server.pid) || true
+            rm server.pid
+          fi
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-failures-node-${{ matrix.node-version }}
+          path: |
+            mtt-*.json
+            tests/**/*.log
+          retention-days: 7

assets/010-ui_initial_load.png

@@ -124,10 +124,16 @@
 
 - The system provides robust controls to handle `real-world workflow` interruptions
 - **Pause/Resume:**
+
   - **Mechanism:** When paused, the `startTime` is nullified, and the elapsed time is stored in `accumulatedMs`
     - When resumed, `startTime` is set back to `Date.now()`
     - The state is saved to the server on each toggle
   - **UX:** Paused timers receive a visual indicator (`orange border`) and their buttons switch to `Resume`
+
+- ![](/assets/020-ui_timer_with_notes.png)
+  _Active timers display real-time duration and control buttons_
+  _Paused timers show orange border and resume option_
+
 - **Delete (Discard):** Allows users to remove accidental or incomplete timers from the active list without generating a permanent record
   - This action also syncs with the server
 - **Notes/Comments:** Each timer includes a textarea for adding detailed notes or comments
@@ -162,6 +168,15 @@
   - **Daily Time Logged (Bar Chart):** Shows total time logged for the last 7 days
 - **Color Consistency:** The `utils.js` module provides deterministic color generation ensuring the same project always gets the same color across charts
 
+### 3.6. Input Validation & Error Handling
+
+- The application provides clear, actionable error messages for invalid input
+- Empty or whitespace-only task names are rejected with helpful guidance
+- Error messages use color-coded styling (red for errors) for immediate recognition
+
+![Error Validation](/assets/030-ui_error_validation.png)
+_Clear error messages guide users to correct input issues_
+
 ## 4. Implementation Details
 
 ### 4.1. Modular Frontend Architecture

assets/020-ui_timer_with_notes.png

@@ -3,6 +3,9 @@
 - The **Multi-Task Time Tracker (MTTT)** runs as a local application on your machine using Node.js
 - The application features a modular architecture with robust error handling to ensure your data remains private and provides a consistent experience across all browsers
 
+![](/assets/010-ui_initial_load.png)
+_The clean, Material Design-inspired interface after setup_
+
 ## 1. Prerequisites
 
 - **Node.js:** You must have Node.js installed on your system (v13 or higher recommended)
@@ -99,3 +102,9 @@ npm run backup
   - Save the file and simply refresh your browser window
   - The new suggestions will appear in the input dropdown
   - No server restart is required
+
+## 7. Using the Application
+
+Once running, you can track time across multiple projects simultaneously:
+
+- ![](/assets/020-ui_timer_with_notes.png)

assets/030-ui_error_validation.png

@@ -47,7 +47,7 @@ export const generateUUID = () => crypto.randomUUID();
  */
 export const formatDuration = (seconds) => {
 	const h = Math.floor(
-		seconds / CONSTANTS.MS_PER_HOUR / CONSTANTS.MS_PER_SECOND
+		seconds / (CONSTANTS.MS_PER_HOUR / CONSTANTS.MS_PER_SECOND)
 	);
 	const m = Math.floor(
 		(seconds % (CONSTANTS.MS_PER_HOUR / CONSTANTS.MS_PER_SECOND)) /

assets/040-ui_reports_view.png

@@ -1 +1,18 @@
-{}
+{
+  "fb7d1a5f-4489-4ad9-9a60-d4ec726b18df": {
+    "project": "Demo Project",
+    "task": "Task with Notes",
+    "startTime": null,
+    "accumulatedMs": 195282,
+    "isPaused": true,
+    "notes": "Mellow World!"
+  },
+  "753d9ee8-1cac-4784-b41c-f46349684c16": {
+    "project": "Test Project",
+    "task": "Test Task",
+    "startTime": "2025-10-31T12:16:10.980Z",
+    "accumulatedMs": 0,
+    "isPaused": false,
+    "notes": "Hello World!"
+  }
+}