@gamerstake/game-core 0.1.0

package/TESTING_OVERVIEW.md

@@ -0,0 +1,378 @@
+# Testing Overview - @gamerstake/game-core
+
+**Complete guide to testing and learning the game-core package**
+
+## Documentation Structure
+
+```
+game-core/
+ README.md ..................... Main documentation & API reference
+ QUICK_START.md ................ Get running in 5 minutes
+ DEVELOPER_GUIDE.md ............ Complete tutorial with examples
+ MANUAL_TESTING.md ............. How to manually test the engine
+ PUBLISHING.md ................. How to publish & distribute
+ TESTING_OVERVIEW.md ........... This file!
+
+ examples/
+ simple-game/
+ server.ts ................ Test server with game rules
+ client.ts ................ Automated test client
+ README.md ................ Manual testing instructions
+
+ tests/
+ Entity.test.ts ............... Unit tests
+ GameLoop.test.ts
+ Room.test.ts
+ ... (12 test files total)
+```
+
+## Choose Your Path
+
+### I want to... → You should...
+
+| Goal | Resource | Time |
+|------|----------|------|
+| **Understand what this package does** | Read [README.md](./README.md) | 5 min |
+| **Get a game running quickly** | Follow [QUICK_START.md](./QUICK_START.md) | 5 min |
+| **Learn to build games** | Read [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) | 30 min |
+| **Manually test the engine** | Follow [MANUAL_TESTING.md](./MANUAL_TESTING.md) | 10 min |
+| **Run automated tests** | Run `pnpm test` | 2 min |
+| **See working code** | Check [examples/simple-game/](./examples/simple-game/) | 10 min |
+| **Publish the package** | Read [PUBLISHING.md](./PUBLISHING.md) | 10 min |
+| **Understand the architecture** | Read RFC docs | 20 min |
+
+## Testing Methods
+
+### 1. Automated Testing (Unit Tests)
+
+**What:** Jest-based unit tests for all components 
+**When:** During development, before commits, in CI/CD 
+**How:**
+
+```bash
+# Run all tests
+pnpm test
+
+# Run with coverage (requires 80% coverage)
+pnpm test:coverage
+
+# Watch mode (auto-rerun on changes)
+pnpm test:watch
+
+# Type checking
+pnpm typecheck
+```
+
+**Coverage:**
+- 12 test files covering all major components
+- Entity system, game loop, networking, spatial grid
+- 80% coverage requirement enforced
+
+**Example test:**
+```typescript
+it('updates position based on velocity and delta time', () => {
+ const entity = new Entity('e1', 0, 0);
+ entity.setVelocity(100, -50);
+ entity.updatePosition(1000); // 1 second
+
+ expect(entity.x).toBe(100);
+ expect(entity.y).toBe(-50);
+});
+```
+
+**See:** `tests/*.test.ts` for examples
+
+---
+
+### 2. Manual Testing (Live Server)
+
+**What:** Run a real multiplayer game server with test clients 
+**When:** Before releases, when testing multiplayer features, debugging 
+**How:**
+
+```bash
+# Step 1: Build
+pnpm build
+
+# Step 2: Start server
+node examples/simple-game/server.js
+
+# Step 3: Start clients (in new terminals)
+node examples/simple-game/client.js
+node examples/simple-game/client.js # More clients!
+```
+
+**What it tests:**
+- Real-time networking
+- State synchronization
+- Multiple concurrent players
+- Performance under load
+- Connection stability
+
+**See:** [MANUAL_TESTING.md](./MANUAL_TESTING.md) for detailed guide
+
+---
+
+### 3. Integration Testing (Your Game)
+
+**What:** Test your game built on game-core 
+**When:** Building your actual game 
+**How:**
+
+Create your own test suite:
+
+```typescript
+// __tests__/MyGame.test.ts
+import { GameServer } from '@gamerstake/game-core';
+import { MyGameRules } from '../src/MyGameRules';
+
+describe('MyGame', () => {
+ it('should award points when collecting items', () => {
+ const gameServer = new GameServer();
+ const room = gameServer.createRoom('test', new MyGameRules());
+
+ // Test your game logic
+ });
+});
+```
+
+**See:** [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) for patterns
+
+## Test Coverage
+
+### What's Tested
+
+| Component | File | Coverage | Tests |
+|-----------|------|----------|-------|
+| **Entities** | Entity.ts | High | Entity.test.ts |
+| **Registry** | Registry.ts | High | Registry.test.ts |
+| **Game Loop** | GameLoop.ts | High | GameLoop.test.ts |
+| **Room** | Room.ts | High | Room.test.ts |
+| **Game Server** | GameServer.ts | High | GameServer.test.ts |
+| **Networking** | Network.ts | High | Network.test.ts |
+| **Snapshots** | Snapshot.ts | High | Snapshot.test.ts |
+| **Spatial Grid** | Grid.ts | High | Grid.test.ts |
+| **Physics** | Movement.ts | High | Movement.test.ts |
+| **Collision** | AABB.ts | High | AABB.test.ts |
+| **Input Queue** | InputQueue.ts | High | InputQueue.test.ts |
+| **RingBuffer** | RingBuffer.ts | High | RingBuffer.test.ts |
+
+### Coverage Requirements
+
+```typescript
+// jest.config.ts
+coverageThreshold: {
+ global: {
+ branches: 80,
+ functions: 80,
+ lines: 80,
+ statements: 80,
+ },
+}
+```
+
+## Quick Commands Reference
+
+```bash
+# AUTOMATED TESTS
+pnpm test # Run all tests once
+pnpm test:watch # Watch mode
+pnpm test:coverage # With coverage report
+pnpm typecheck # Type checking only
+
+# BUILD
+pnpm build # Build for production
+pnpm dev # Build + watch
+
+# MANUAL TESTING
+node examples/simple-game/server.js # Start test server
+node examples/simple-game/client.js # Start test client
+
+# LINTING
+pnpm lint # Check code style
+
+# CLEAN
+pnpm clean # Remove dist/
+```
+
+## Learning Path
+
+### For Complete Beginners
+
+1. **Read** [README.md](./README.md) - Understand what game-core is
+2. **Follow** [QUICK_START.md](./QUICK_START.md) - Get something running
+3. **Try** Manual testing - See it work live
+4. **Read** [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) - Learn patterns
+5. **Build** Your first game!
+
+### For Experienced Developers
+
+1. **Skim** [README.md](./README.md) - API overview
+2. **Read** [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) - Advanced patterns
+3. **Review** `tests/` - See usage examples
+4. **Build** Your game!
+
+### For Contributors
+
+1. **Read** Architecture RFC docs
+2. **Study** Source code (well-documented)
+3. **Run** `pnpm test:coverage`
+4. **Write** Tests for new features
+5. **Submit** PRs with tests
+
+## Troubleshooting Testing
+
+### Tests Won't Run
+
+```bash
+# Install dependencies
+pnpm install
+
+# Check Node version (needs 20+)
+node --version
+
+# Try clean install
+rm -rf node_modules package-lock.json
+pnpm install
+```
+
+### Tests Failing
+
+```bash
+# Run specific test file
+pnpm test Entity.test.ts
+
+# Run with verbose output
+pnpm test --verbose
+
+# Update snapshots (if using)
+pnpm test -u
+```
+
+### Manual Testing Issues
+
+See [MANUAL_TESTING.md](./MANUAL_TESTING.md) troubleshooting section.
+
+### Coverage Not Meeting Threshold
+
+```bash
+# Check which files need more tests
+pnpm test:coverage
+
+# View HTML report
+open coverage/index.html
+```
+
+## Performance Testing
+
+### Monitoring Metrics
+
+The manual test server logs performance metrics:
+
+```
+ Room: 3 players, 8 entities, Avg tick: 12.34ms
+```
+
+**Targets:**
+- **Good:** < 40ms avg tick time
+- **Warning:** 40-50ms (optimization recommended)
+- **Critical:** > 50ms (dropping frames)
+
+### Load Testing
+
+```bash
+# Start server
+node examples/simple-game/server.js
+
+# In separate terminals, start many clients
+for i in {1..20}; do
+ node examples/simple-game/client.js &
+done
+
+# Watch server metrics
+```
+
+### Profiling
+
+Add profiling to your game rules:
+
+```typescript
+onTick(room: Room, delta: number) {
+ console.time('tick');
+
+ // Your game logic
+
+ console.timeEnd('tick');
+}
+```
+
+## Test-Driven Development
+
+### Writing Tests for Your Game
+
+```typescript
+// 1. Write the test
+it('should damage enemy when attacked', () => {
+ const room = createTestRoom();
+ const player = room.getRegistry().get('player-1');
+ const enemy = room.getRegistry().get('enemy-1');
+
+ player.attack(enemy);
+
+ expect(enemy.health).toBe(75); // Started at 100, took 25 damage
+});
+
+// 2. Implement the feature
+class Player extends Entity {
+ attack(target: Entity) {
+ target.health -= this.attackPower;
+ target.markDirty();
+ }
+}
+
+// 3. Run test
+pnpm test
+```
+
+## Additional Resources
+
+### Documentation
+
+- **[README.md](./README.md)** - Main API reference
+- **[QUICK_START.md](./QUICK_START.md)** - 5-minute tutorial
+- **[DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md)** - Complete guide
+- **[MANUAL_TESTING.md](./MANUAL_TESTING.md)** - Testing instructions
+- **[PUBLISHING.md](./PUBLISHING.md)** - Publishing and distribution
+
+### Examples
+
+- **[examples/simple-game/](./examples/simple-game/)** - Working server & client
+
+### Tests
+
+- **[tests/](./tests/)** - Unit test examples
+
+### Source Code
+
+- **[src/](./src/)** - Well-documented source (read for advanced usage)
+
+## Getting Help
+
+1. **Check docs** - Start with [QUICK_START.md](./QUICK_START.md)
+2. **Read examples** - See working code in `examples/`
+3. **Review tests** - See patterns in `tests/`
+4. **Check source** - Code is well-documented
+5. **Contact team** - GamerStake engineering team
+
+---
+
+## Summary
+
+ **Automated testing** with Jest - `pnpm test` 
+ **Manual testing** with live server - See [MANUAL_TESTING.md](./MANUAL_TESTING.md) 
+ **Developer guide** - See [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) 
+ **Quick start** - See [QUICK_START.md](./QUICK_START.md) 
+ **Examples** - See `examples/simple-game/` 
+ **High coverage** - 80% threshold enforced 
+
+**You're ready to test and build with game-core! **