new: pkg: add test cases to back-end w/ real database connection in it #10

docs/README.md

@@ -1,6 +1,6 @@
 # Mine-Seeker Game Documentation
 
-This directory contains comprehensive documentation about the Mine-Seeker game mechanics and implementation.
+This directory contains comprehensive documentation about the Mine-Seeker game mechanics, testing, and implementation.
 
 ## Game Mechanics
 
@@ -18,6 +18,46 @@ Complete reference for the bonus points system including:
 
 ---
 
+## Testing
+
+### [Testing Guide](./testing/TESTING.md)
+Complete testing setup and best practices including:
+- Test environment configuration
+- Database isolation with DAMA Doctrine Test Bundle
+- Test database setup (`mineseeker_test`)
+- Writing effective tests
+- Running tests (all, specific, with coverage)
+- Best practices (AAA pattern, factories, type hints)
+- CI/CD integration examples
+- Troubleshooting guide
+
+**Recommended for**: All developers, understanding test infrastructure, writing new tests, debugging test failures.
+
+### [Factory Documentation](./testing/FACTORIES.md)
+Detailed API reference for Zenstruck Foundry factories:
+- All available factories (User, Gamer, PlayedGame, Step, Grid, etc.)
+- Factory usage examples
+- Creating related entities
+- Repository access
+- Database isolation explanation
+- Best practices and patterns
+
+**Recommended for**: Writing tests with test data, understanding factory patterns, creating complex test scenarios.
+
+---
+
+## Technical Documentation
+
+### [Fonts](./FONTS.md)
+TrueType fonts used for server-side image generation:
+- Font file locations
+- Usage in battle card generation
+- Web vs. server-side font formats
+
+**Recommended for**: Working on OG image generation, understanding font rendering.
+
+---
+
 ## Quick Reference
 
 ### Bonus Points at a Glance
@@ -30,18 +70,63 @@ Complete reference for the bonus points system including:
 | Chain Combo | Tracked | Consecutive mine clicks (no safe clicks) |
 | Biggest Reveal | Tracked | Largest number of safe cells revealed |
 
-### Key Rules
-- Safe cell bonus only awarded for ≥2 cells minimum
-- Chain counter resets on any safe cell click
-- Endgame threshold: 51 - (redPoints + bluePoints) ≤ 10
-- Bonus stats are per-player and persist in database
+### Available Test Factories
+| Factory | Entity | Purpose |
+|---------|--------|---------|
+| `UserFactory` | `User` | Registered users |
+| `GamerFactory` | `Gamer` | Anonymous/guest players |
+| `PlayedGameFactory` | `PlayedGame` | Game records |
+| `StepFactory` | `Step` | Game moves |
+| `GridFactory` | `Grid` | Game grids (16×16) |
+| `GridRowFactory` | `GridRow` | Grid rows |
+| `WebAuthnCredentialFactory` | `WebAuthnCredential` | Passkey credentials |
+| `ContactMessageFactory` | `ContactMessage` | Contact messages |
+
+### Running Tests
+```bash
+# Recommended: Use Makefile
+make test-db-setup
+
+# Or manually:
+# All tests
+vendor/bin/phpunit
+
+# Specific file
+vendor/bin/phpunit tests/Controller/ProfileControllerTest.php
+
+# Specific method
+vendor/bin/phpunit --filter testProfilePageRequiresAuthentication
+
+# With coverage (requires Xdebug/PCOV)
+XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage/
+
+# With increased memory
+php -d memory_limit=512M vendor/bin/phpunit
+```
 
 ---
 
 ## Files Using This Information
+
+### Game Mechanics
 - Backend: `/src/Util/TopicManager.php`
 - Frontend: `/assets/js/mine-seeker/contexts/GameProvider.jsx`
 - UI: `/assets/js/mine-seeker/components/BonusStatsDialog.jsx`
 - Constants: `/assets/js/mine-seeker/utils/constants.jsx`
 
+### Testing
+- Test Base Class: `/tests/WebTestCase.php`
+- Factories: `/tests/Factory/`
+- Example Tests: `/tests/Integration/FactoryExampleTest.php`
+- PHPUnit Config: `/phpunit.dist.xml`
+- Bundle Config: `/config/bundles.php`
 
+---
+
+## Additional Resources
+
+- **[Main README](../README.md)** - Project overview, installation, deployment
+- **[AI Agent Guidelines](../AGENTS.md)** - Comprehensive guide for AI coding agents
+- **[Zenstruck Foundry](https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html)** - Official Foundry documentation
+- **[PHPUnit](https://phpunit.de/)** - PHPUnit documentation
+- **[Symfony Testing](https://symfony.com/doc/current/testing.html)** - Symfony testing guide