Merge pull request #14 from offendingcommit/fix/state-persistence-issues

feat: comprehensive testing infrastructure and state persistence improvements

Author: offendingcommit

.github/workflows/ci.yml

@@ -48,16 +48,16 @@ jobs:
         poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --exclude=.venv,.git,__pycache__,build,dist
         poetry run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics --exclude=.venv,.git,__pycache__,build,dist
     
-    - name: Format check with black
-      run: poetry run black --check --exclude=\.venv --extend-exclude=main.py .
-    
     - name: Import sorting check with isort
       run: poetry run isort --check --skip .venv --skip main.py .
 
     - name: Test with pytest
       run: |
         if [ -d "src" ]; then
-          poetry run pytest --cov=src
+          # Run unit tests first (fast, < 5 seconds)
+          poetry run pytest tests/test_*_unit.py -v --tb=short
+          # Run full test suite with coverage, excluding slow/browser/integration/flaky tests
+          poetry run pytest --cov=src --cov-report=xml --cov-report=term-missing -m "not e2e and not playwright and not slow and not integration and not flaky"
         else
           echo "No src directory yet, skipping tests"
           exit 0

.github/workflows/release-pipeline.yml

@@ -43,16 +43,16 @@ jobs:
         poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --exclude=.venv,.git,__pycache__,build,dist
         poetry run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics --exclude=.venv,.git,__pycache__,build,dist
     
-    - name: Format check with black
-      run: poetry run black --check --exclude=\.venv --extend-exclude=main.py .
-    
     - name: Import sorting check with isort
       run: poetry run isort --check --skip .venv --skip main.py .
 
     - name: Test with pytest
       run: |
         if [ -d "src" ]; then
-          poetry run pytest --cov=src
+          # Run unit tests first (fast, < 5 seconds)
+          poetry run pytest tests/test_*_unit.py -v --tb=short
+          # Run full test suite with coverage, excluding slow/browser/integration/flaky tests
+          poetry run pytest --cov=src --cov-report=xml --cov-report=term-missing -m "not e2e and not playwright and not slow and not integration and not flaky"
         else
           echo "No src directory yet, skipping tests"
           exit 0

.gitignore

@@ -53,3 +53,7 @@ Thumbs.db
 # Poetry lock file (optional – some teams prefer to version-control this)
 poetry.lock
 .nicegui/
+.serena/cache/
+
+# Game state persistence file
+game_state.json

.serena/memories/bingo_project_overview.md

@@ -0,0 +1,43 @@
+# Bingo Project Overview
+
+## Purpose
+A customizable bingo board generator built with NiceGUI and Python. Creates interactive bingo games for streams, meetings, or events with shareable view-only links.
+
+## Tech Stack
+- **Language**: Python 3.12+
+- **UI Framework**: NiceGUI (reactive web UI)
+- **Package Manager**: Poetry
+- **Testing**: pytest with coverage
+- **Linting**: flake8, black, isort, mypy
+- **Containerization**: Docker
+- **Orchestration**: Kubernetes with Helm charts
+- **CI/CD**: GitHub Actions with semantic-release
+- **Web Server**: FastAPI (via NiceGUI)
+
+## Project Structure
+- `app.py`: Main entry point (modular structure)
+- `main.py`: Legacy monolithic entry point
+- `src/`: Source code
+  - `config/`: Configuration and constants
+  - `core/`: Core game logic
+  - `ui/`: UI components (routes, sync, controls, board)
+  - `utils/`: Utilities (file operations, text processing)
+  - `types/`: Type definitions
+- `tests/`: Unit and integration tests
+- `phrases.txt`: Customizable bingo phrases
+- `static/`: Static assets (fonts)
+- `helm/`: Kubernetes deployment configs
+
+## Key Features
+- Custom phrases from file
+- Shareable view-only boards
+- Interactive click-to-mark tiles
+- Stream integration support
+- Responsive design
+- State persistence
+- Real-time synchronization between views
+
+## Environment Variables
+- `PORT`: Port number (default: 8080)
+- `HOST`: Host address (default: 0.0.0.0)
+- `DEBUG`: Debug mode (default: False)

.serena/memories/code_style_conventions.md

@@ -0,0 +1,81 @@
+# Bingo Project - Code Style & Conventions
+
+## Python Code Style
+
+### General Guidelines
+- **Python Version**: 3.12+
+- **Line Length**: 88 characters (Black's default)
+- **Indentation**: 4 spaces (no tabs)
+- **String Formatting**: Use f-strings for interpolation
+
+### Imports
+1. Standard library imports first
+2. Third-party imports second
+3. Local module imports last
+4. Each group alphabetically sorted
+5. Use `from typing import` for type hints
+
+Example:
+```python
+import datetime
+import logging
+import random
+from typing import List, Optional, Set, Dict, Any
+
+from nicegui import ui, app
+
+from src.config.constants import HEADER_TEXT
+from src.types.ui_types import BoardType
+```
+
+### Naming Conventions
+- **Functions/Variables**: `snake_case`
+- **Constants**: `UPPER_CASE` (defined at top of file)
+- **Classes**: `PascalCase`
+- **Type Aliases**: `PascalCase`
+- **Private Methods**: `_leading_underscore`
+
+### Type Hints
+- Use type hints for all function signatures
+- Use `Optional[T]` for nullable types
+- Use `List`, `Dict`, `Set`, `Tuple` from typing
+- Define custom types in `src/types/`
+
+### Documentation
+- Triple-quoted docstrings for modules and functions
+- Brief description at module level
+- No inline comments unless absolutely necessary
+- Descriptive variable/function names over comments
+
+### Error Handling
+- Use try/except blocks with specific exceptions
+- Log errors using the logging module
+- Provide meaningful error messages
+
+### NiceGUI Specific
+- Define UI element styling as class constants
+- Use context managers for UI containers
+- Separate UI logic from business logic
+- Handle disconnected clients gracefully
+
+### Code Organization
+- Keep functions focused and single-purpose
+- Extract constants to config module
+- Separate concerns into appropriate modules
+- Use type definitions for complex data structures
+
+### Testing Conventions
+- Test files: `test_*.py`
+- Test classes: `Test*`
+- Test functions: `test_*`
+- Use pytest fixtures for setup
+- Mock external dependencies
+- Aim for high test coverage
+
+## Formatting Tools
+- **Black**: Automatic code formatting
+- **isort**: Import sorting with Black compatibility
+- **flake8**: Linting (configured for 88 char lines)
+- **mypy**: Static type checking
+
+All formatting is automated via `make format` or individual Poetry commands.

.serena/memories/git_history_insights.md

@@ -0,0 +1,44 @@
+# Bingo Project - Git History Insights
+
+## Recent Development (March 2025)
+- Latest commit: `da9cde7` - feat: persist state (main branch)
+- Feature branch exists: `feature/persisting-state` with WIP changes
+- Author: Jonathan Irvin <djfoxyslpr@gmail.com>
+
+## Version History
+- Current version: v1.1.4 (released via semantic versioning)
+- Major milestones:
+  - v1.0.0: Major release with semantic versioning established
+  - v0.1.0: Initial modular architecture refactoring
+  
+## Key Development Patterns
+1. **Conventional Commits**: Strictly follows format (feat, fix, chore, docs, test, refactor)
+2. **Automated Releases**: Uses python-semantic-release with [skip ci] tags
+3. **PR-based Workflow**: Features developed in branches, merged via PRs
+4. **Code Quality**: Every PR includes formatting (black, isort) and testing
+
+## Recent Changes (v1.1.4)
+- State persistence implementation (March 16, 2025)
+- Health check improvements with JSON formatting
+- Import sorting and formatting fixes
+- Added comprehensive state persistence tests (459 lines)
+- Enhanced board builder tests (257 lines)
+
+## Architecture Evolution Timeline
+1. Initial monolithic `main.py` implementation
+2. Modular refactoring (v0.1.0) - split into src/ structure
+3. UI improvements - closed game message display
+4. NiceGUI 2.11+ compatibility fixes
+5. State persistence across app restarts (latest)
+
+## Testing Evolution
+- Started with basic tests
+- Added comprehensive unit tests (80% coverage)
+- Latest: Extensive state persistence testing
+- Focus on UI synchronization and user tracking
+
+## CI/CD Pipeline
+- GitHub Actions for automated testing and releases
+- Disabled Docker and Helm workflows (kept as reference)
+- Semantic versioning based on commit messages
+- Automatic CHANGELOG.md updates

.serena/memories/incomplete_branch_strategy.md

@@ -0,0 +1,111 @@
+# Strategy for Handling Incomplete Remote Branches
+
+## Overview
+When returning to a project with incomplete work in remote branches, a systematic approach helps assess and decide how to proceed with each branch.
+
+## Discovery Commands
+```bash
+# List all branches
+git branch -a
+
+# Find unmerged branches
+git branch --no-merged main
+
+# Recent branch activity
+git for-each-ref --sort=-committerdate refs/remotes/origin --format='%(committerdate:short) %(refname:short) %(subject)'
+
+# Check specific branch differences
+git log main..origin/branch-name --oneline
+git diff main...origin/branch-name --stat
+```
+
+## Decision Framework
+
+### 1. Create Draft PR
+**When**: Work is partially complete but needs visibility
+```bash
+gh pr create --draft --base main --head branch-name --title "WIP: Description"
+```
+**Benefits**: 
+- Documents intent and approach
+- Allows collaboration
+- Preserves context
+- Shows in PR list for tracking
+
+### 2. Local Continuation
+**When**: Work is experimental or very incomplete
+```bash
+git checkout branch-name
+git pull origin branch-name
+# Option A: Continue directly
+# Option B: Stash current state first
+git stash push -m "Previous WIP attempt"
+```
+
+### 3. Rebase and Cleanup
+**When**: Commits need reorganization before review
+```bash
+git checkout branch-name
+git rebase -i main
+# Clean up commit history
+```
+
+### 4. Extract Useful Parts
+**When**: Some ideas are good but implementation needs restart
+```bash
+# Cherry-pick specific commits
+git cherry-pick commit-hash
+
+# Or create patches
+git format-patch main..branch-name
+```
+
+## Best Practices
+
+1. **Use Git Worktrees** for isolated testing:
+   ```bash
+   git worktree add ../project-wip branch-name
+   ```
+
+2. **Document Intent**: 
+   - Check commit messages for TODOs
+   - Look for related issues
+   - Add comments to draft PRs
+
+3. **Test Before Deciding**:
+   ```bash
+   poetry install
+   poetry run pytest
+   poetry run flake8
+   ```
+
+4. **Communicate Status**:
+   - Update PR descriptions
+   - Close stale branches
+   - Document decisions
+
+## Handling "WIP and Broken" Commits
+
+1. First understand what's broken:
+   - Run tests to see failures
+   - Check linting errors
+   - Try running the application
+
+2. Decide on approach:
+   - Fix and continue if close to working
+   - Extract concepts if fundamentally flawed
+   - Archive with explanation if obsolete
+
+3. Clean up before merging:
+   - Squash WIP commits
+   - Write proper commit messages
+   - Ensure all tests pass
+
+## Branch Lifecycle Management
+
+- **Active**: Currently being developed
+- **Draft PR**: Under review/discussion
+- **Stale**: No activity >30 days
+- **Archived**: Kept for reference but not active
+
+Regular cleanup prevents accumulation of dead branches while preserving useful experimental work.

.serena/memories/nicegui_storage_architecture_findings.md

@@ -0,0 +1,53 @@
+# NiceGUI Storage Architecture Findings
+
+## Key Discoveries from Documentation
+
+### 1. Application Lifecycle
+- NiceGUI apps start with `ui.run()` which launches the web server
+- The app uses FastAPI/Starlette underneath with Uvicorn as the ASGI server
+- Frontend uses Vue.js, Quasar, and Tailwind CSS
+
+### 2. Storage Implementation Details
+From the documentation analysis:
+- No explicit mention of `app.storage.general` being client-side localStorage
+- Storage appears to be a NiceGUI abstraction but implementation details not clear
+- The framework focuses on reactive UI elements, not persistent storage
+
+### 3. Server Architecture
+- Built on top of FastAPI (ASGI framework)
+- Uses WebSocket connections for real-time updates
+- Docker deployment is well-supported
+- Can run behind reverse proxies (nginx examples provided)
+
+### 4. Missing Information
+The documentation doesn't clearly explain:
+- Whether `app.storage` is server-side or client-side
+- How storage persists across server restarts
+- Best practices for state persistence
+- Lifecycle hooks for initialization
+
+## Implications for Our Issue
+
+1. **Storage Type Unclear**: The docs don't confirm if `app.storage.general` is browser localStorage or server-side storage
+
+2. **No State Persistence Examples**: No examples show persisting game state across server restarts
+
+3. **Docker/Production Focus**: Examples focus on deployment but not on state management
+
+4. **Testing Approach**: The testing framework uses a `Screen` class for UI testing, not state persistence testing
+
+## Recommended Architecture Based on Findings
+
+Since NiceGUI documentation doesn't provide clear guidance on persistent storage:
+
+1. **Assume Client-Side**: Treat `app.storage.general` as client-side until proven otherwise
+2. **Implement Server-Side**: Create our own server-side persistence layer
+3. **Use FastAPI Features**: Leverage the underlying FastAPI for lifecycle management
+4. **File/DB Storage**: Implement file or database storage independent of NiceGUI
+
+## Next Steps
+
+1. Test if `app.storage.general` survives server restarts (empirical testing)
+2. Implement server-side storage solution (file or SQLite)
+3. Use FastAPI lifecycle events for initialization
+4. Create proper state management layer