菜单
Phaser unit testing patterns with MockScene. Provides patterns for testing Phaser objects, Matter.js physics, and game systems without requiring a running game instance.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/feliperyba/ralph-orchestra --skill qa-phaser-unit-testing命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | qa-phaser-unit-testing |
| description | Phaser unit testing patterns with MockScene. Provides patterns for testing Phaser objects, Matter.js physics, and game systems without requiring a running game instance. |
| category | testing |
"Test Phaser game objects without a running game instance."
Use when creating unit tests for:
CRITICAL LESSON FROM BUG-011: Never use real Phaser Scene instances in unit tests. They require a running Phaser Game instance and will fail with errors like "scene.init is not a function". Always use MockScene pattern.
Real Phaser Scenes need:
This makes unit tests:
MockScene Pattern Solution: Create comprehensive mocks that simulate Phaser Scene APIs without requiring the full engine.
// tests/helpers/MockScene.ts
import { } ;
{
: ;
: ;
: ;
: { : ; : };
: { : ; : };
: ;
}
{
: ;
: ;
: ;
: ;
: ;
: ;
: ;
}
{
: ;
: ;
: ;
}
{
: ;
}
{
: {
: {
: ;
}
};
: {
: ;
: ;
: ;
};
: {
: { : ; : };
};
: {
: ;
};
: {
: ;
};
: {
: { : };
: { : };
: ;
};
: <, <>> = ();
() {
();
.();
}
() {
. = {
: {
: ({
: {
: key,
: ,
: ,
: { x, y },
: { : , : },
: ,
},
: {},
: {},
: {},
: {},
: {},
: {},
}),
},
};
. = {
: {
.(event, ...args);
},
: {
(!..(event)) {
..(event, ());
}
..(event)!.(handler);
.(event, handler);
},
: {
(handler) {
..(event)?.(handler);
.(event, handler);
} {
..(event);
.(event);
}
},
};
. = {
: ({
: {},
: {},
}),
};
. = {
: {
: {},
},
};
. = {
: ({
: ,
: ,
: {},
}),
};
. = {
: ({ : {} }),
: ({ : {} }),
: ,
};
}
() {
..();
.();
}
}
// tests/unit/objects/Pig.test.ts
import { describe, test, expect, beforeEach, vi } from 'vitest';
import { MockScene } from '../helpers/MockScene';
import { SmallPig } from '@/objects/pigs/SmallPig';
describe('SmallPig', () => {
let scene: MockScene;
beforeEach(() => {
scene = new MockScene();
});
describe('initialization', () => {
test('should create pig with correct health', () => {
const pig = new SmallPig(scene, 100, 200);
expect(pig.health).toBe(10);
expect(pig.maxHealth).toBe(10);
});
test('should create pig with correct scale', () => {
const pig = new SmallPig(scene, 100, 200);
// MockScene creates mock body with position
expect(pig.body).toBeDefined();
});
});
describe('damage system', () => {
test('should reduce health when damaged', () => {
const pig = new SmallPig(scene, 100, 200);
pig.takeDamage(5);
expect(pig.health).toBe(5);
});
test('should be destroyed when health reaches 0', () => {
const pig = new SmallPig(scene, 100, 200);
const destroyedSpy = vi.fn();
scene.on('pig-destroyed', destroyedSpy);
pig.takeDamage(10);
expect(pig.isDestroyed()).toBe(true);
expect(destroyedSpy).toHaveBeenCalledWith(pig);
});
});
describe('visual damage state', () => {
test('should show damage when health > 50% lost', () => {
const pig = new SmallPig(scene, 100, 200);
pig.takeDamage(6); // 60% damage
expect(pig.shouldShowDamageState()).toBe(true);
});
});
});
// tests/unit/systems/PigHealthSystem.test.ts
import { describe, test, expect, beforeEach, vi } from 'vitest';
import { MockScene } from '../helpers/MockScene';
import { PigHealthSystem } from '@/systems/PigHealthSystem';
import { SmallPig } from '@/objects/pigs/SmallPig';
describe('PigHealthSystem', () => {
let scene: MockScene;
let system: PigHealthSystem;
beforeEach(() => {
scene = new MockScene();
system = new PigHealthSystem(scene);
});
test('should track all pigs in scene', () => {
const pig1 = new SmallPig(scene, 100, 200);
const pig2 = new SmallPig(scene, 300, 200);
system.trackPig(pig1);
system.trackPig(pig2);
expect(system.trackedPigCount).toBe(2);
});
test('should emit event when all pigs destroyed', () => {
const pig = new SmallPig(scene, 100, 200);
system.trackPig(pig);
const allDestroyedSpy = vi.fn();
scene.on('all-pigs-destroyed', allDestroyedSpy);
pig.takeDamage(10); // Destroy pig
expect(allDestroyedSpy).toHaveBeenCalled();
});
});
// tests/unit/objects/birds/YellowBird.test.ts
import { describe, test, expect, beforeEach } from 'vitest';
import { MockScene } from '../../helpers/MockScene';
import { YellowBird } from '@/objects/birds/YellowBird';
describe('YellowBird', () => {
let scene: MockScene;
let bird: YellowBird;
beforeEach(() => {
scene = new MockScene();
bird = new YellowBird(scene, 100, 200);
});
describe('speed boost ability', () => {
test('should increase velocity by 2.5x when activated', () => {
bird.body.velocity = { x: 10, y: 0 };
bird.activateAbility();
expect(bird.body.velocity.x).toBe(25);
});
test('should emit ability-activated event', () => {
const spy = vi.fn();
scene.on('ability-activated', spy);
bird.activateAbility();
expect(spy).toHaveBeenCalledWith('yellow-boost', expect.any(Object));
});
});
});
// tests/unit/physics/CollisionTest.test.ts
import { describe, test, expect, beforeEach } from 'vitest';
import { MockScene } from '../../helpers/MockScene';
import { Block } from '@/objects/Block';
describe('Block Collision', () => {
let scene: MockScene;
beforeEach(() => {
scene = new MockScene();
});
test('should detect collision between two blocks', () => {
const block1 = new Block(scene, 100, 100, 'wood');
const block2 = new Block(scene, 100, 100, 'glass');
// Simulate collision
block1.onCollide(block2);
expect(block1.hasCollided).toBe(true);
});
test('should transfer momentum on collision', () => {
const block1 = new Block(scene, 100, 100, 'wood');
const block2 = new Block(scene, 100, 100, 'glass');
block1.body.velocity = { x: 10, y: 0 };
block2.body.velocity = { x: 0, y: 0 };
block1.onCollide(block2);
// Verify momentum transfer
expect(block2.body.velocity.x).toBeGreaterThan(0);
});
});
tests/
├── helpers/
│ └── MockScene.ts # Shared mock implementation
├── unit/
│ ├── objects/
│ │ ├── birds/
│ │ │ ├── RedBird.test.ts
│ │ │ ├── YellowBird.test.ts
│ │ │ └── BlackBird.test.ts
│ │ ├── pigs/
│ │ │ ├── Pig.test.ts
│ │ │ ├── SmallPig.test.ts
│ │ │ └── LargePig.test.ts
│ │ └── blocks/
│ │ └── Block.test.ts
│ └── systems/
│ ├── PigHealthSystem.test.ts
│ ├── BirdAbilityManager.test.ts
│ └── ScoringSystem.test.ts
| Issue | Cause | Solution |
|---|---|---|
| "scene.init is not a function" | Using real Scene instead of MockScene | Replace with MockScene |
| "Cannot read properties of undefined" | Missing mock properties | Add missing property to MockScene |
| Event handlers not being called | Event system not mocked | Implement events.on/off/emit in MockScene |
| Tween-related failures | Tweens not mocked | Add tweens.add mock to MockScene |
| "matter.add is not a function" | Matter.js not mocked | Add matter.add mock to MockScene |
scene.time.addEvent, mock it❌ DON'T:
// WRONG - Using real Scene
import { Game, Scene } from 'phaser';
test('should create pig', () => {
const game = new Game(config); // Slow and brittle
const scene = new Scene();
game.scene.add('test', scene);
// ... tests will fail if canvas not in DOM
});
✅ DO:
// RIGHT - Using MockScene
import { MockScene } from '../helpers/MockScene';
test('should create pig', () => {
const scene = new MockScene(); // Fast and reliable
const pig = new SmallPig(scene, 100, 200);
expect(pig.health).toBe(10);
});
tests/unit/objects/Pig.test.ts - Reference implementationLESSON LEARNED FROM BUG-011: The MockScene pattern is essential for testing Phaser objects. Always create comprehensive mocks for all Phaser Scene properties used by your code. This prevents test failures caused by missing Phaser Game instances.
Lesson from feat-027 (Star Rating Preview): UI components with animations require specific testing patterns.
// tests/unit/ui/HUD.test.ts
import { describe, test, expect, beforeEach, vi } from 'vitest';
import { MockScene } from '../helpers/MockScene';
import { HUD } from '@/ui/HUD';
describe('HUD Star Rating Preview', () => {
let scene: MockScene;
let hud: HUD;
beforeEach(() => {
scene = new MockScene();
hud = new HUD(scene);
});
describe('star threshold calculation', () => {
test('should calculate 2-star threshold correctly per level', () => {
// Level 1: 32,000 + (1 × 2,000) = 34,000
expect(hud.getTwoStarThreshold(1)).toBe(34000);
// Level 5: 32,000 + (5 × 2,000) = 42,000
expect(hud.getTwoStarThreshold(5)).toBe(42000);
});
test('should calculate 3-star threshold correctly per level', () => {
// Level 1: 66,000 + (1 × 6,000) = 72,000
expect(hud.getThreeStarThreshold(1)).toBe(72000);
// Level 10: 66,000 + (10 × 6,000) = 126,000
expect(hud.getThreeStarThreshold(10)).toBe(126000);
});
});
describe('star fill state updates', () => {
test('should show first star filled when score exceeds first threshold', () => {
hud.updateStarRating(10000, 1); // Below 34,000
// Verify star 0 is empty (gray, low alpha)
expect(hud.stars[0].tintTopLeft).toBe(0xcccccc);
expect(hud.stars[0].alpha).toBeLessThan(0.5);
});
test('should show second star filled when score exceeds threshold', () => {
hud.updateStarRating(35000, 1); // Above 34,000
// Verify star 0 is filled (yellow, full alpha)
expect(hud.stars[0].tintTopLeft).toBe(0xffcc00);
expect(hud.stars[0].alpha).toBe(1.0);
});
});
describe('animation behavior', () => {
test('should create tween when star state changes', () => {
const tweenSpy = vi.fn();
scene.tweens.add = tweenSpy;
hud.updateStarRating(0, 1); // Zero score
hud.updateStarRating(35000, 1); // Above first threshold
// Should have created tweens for animation
expect(tweenSpy).toHaveBeenCalled();
});
test('should kill existing tweens before creating new ones', () => {
const killSpy = vi.fn();
scene.tweens.killTweensOf = killSpy;
// Update twice to trigger tween cleanup
hud.updateStarRating(10000, 1);
hud.updateStarRating(35000, 1);
// Should kill old tweens to prevent accumulation
expect(killSpy).toHaveBeenCalled();
});
});
});
describe('real-time score updates', () => {
test('should update star display as score increases', () => {
const updateSpy = vi.fn();
hud.on('star-updated', updateSpy);
// Simulate score increases over time
hud.updateStarRating(10000, 1);
hud.updateStarRating(20000, 1);
hud.updateStarRating(34000, 1); // Should trigger star fill
expect(updateSpy).toHaveBeenCalledTimes(3);
});
test('should handle rapid score updates efficiently', () => {
const startTime = performance.now();
// Simulate 60 updates per second
for (let i = 0; i < 60; i++) {
hud.updateStarRating(i * 100, 1);
}
const duration = performance.now() - startTime;
// Should complete in under 16ms (one frame)
expect(duration).toBeLessThan(16);
});
});
| Issue | Symptoms | Solution |
|---|---|---|
| Tweens accumulate | Frame drops over time | Kill existing tweens before creating new ones |
| State not updating | Visuals don't change | Verify event listeners are attached |
| Thresholds wrong | Stars fill at wrong scores | Test calculation with multiple level values |
| Performance drops | Laggy UI | Don't tween on every frame, only on state change |
Complete Developer workflow orchestration - task research sequence, implementation flow, validation gates, PRD synchronization, exit conditions.
Complete Game Designer workflow - skill invocation protocol, GDD creation, playtest flow with GDD review, design sessions. MUST load before starting assignments.
Complete PM Coordinator workflow - task assignment, project orchestration, PRD management, worker coordination. Use proactively when starting PM agent work.