@reldens/skills 0.46.0 → 0.47.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/.claude/architecture.md +472 -0
  2. package/.claude/class-hierarchy.md +982 -0
  3. package/.claude/event-system-architecture.md +475 -0
  4. package/.claude/level-progression.md +1259 -0
  5. package/.claude/skill-execution-flow.md +979 -0
  6. package/.claude/testing-guide.md +356 -0
  7. package/.claude/testing-patterns.md +1096 -0
  8. package/CLAUDE.md +164 -29
  9. package/lib/class-path.js +13 -10
  10. package/lib/client/receiver.js +1 -3
  11. package/lib/levels-set.js +24 -17
  12. package/lib/server/sender.js +1 -1
  13. package/lib/skill.js +19 -16
  14. package/lib/types/attack.js +28 -11
  15. package/lib/types/effect.js +10 -4
  16. package/lib/types/physical-attack.js +2 -2
  17. package/lib/types/physical-effect.js +2 -2
  18. package/lib/types/physical-properties-validator.js +1 -1
  19. package/lib/types/physical-skill-runner.js +5 -5
  20. package/package.json +9 -3
  21. package/tests/fixtures/levels/base-levels.js +89 -0
  22. package/tests/fixtures/mocks/mock-client.js +44 -0
  23. package/tests/fixtures/mocks/mock-owner.js +60 -0
  24. package/tests/fixtures/mocks/mock-target.js +50 -0
  25. package/tests/fixtures/skills/base-skills.js +80 -0
  26. package/tests/run-tests.js +88 -0
  27. package/tests/unit/client/test-receiver.js +249 -0
  28. package/tests/unit/server/test-sender.js +527 -0
  29. package/tests/unit/test-class-path.js +1239 -0
  30. package/tests/unit/test-level.js +176 -0
  31. package/tests/unit/test-levels-set.js +1227 -0
  32. package/tests/unit/test-server.js +266 -0
  33. package/tests/unit/test-skill.js +1302 -0
  34. package/tests/unit/types/test-attack.js +1195 -0
  35. package/tests/unit/types/test-effect.js +587 -0
  36. package/tests/unit/types/test-physical-attack.js +564 -0
  37. package/tests/unit/types/test-physical-effect.js +769 -0
  38. package/tests/unit/types/test-physical-properties-validator.js +203 -0
  39. package/tests/unit/types/test-physical-skill-runner.js +348 -0
  40. package/tests/utils/test-helpers.js +122 -0
@@ -0,0 +1,356 @@
1
+ # Testing Guide
2
+
3
+ ## Overview
4
+
5
+ The `@reldens/skills` package uses Node.js built-in test runner for all unit tests. This guide explains how to write and run tests effectively.
6
+
7
+ ## Test Runner
8
+
9
+ The test runner is located at `tests/run-tests.js` and provides:
10
+
11
+ - Automatic test file discovery (files starting with `test-` in `tests/unit/`)
12
+ - Concurrent test execution
13
+ - Filtering support for running specific tests
14
+ - Proper error handling and exit codes
15
+
16
+ ## Running Tests
17
+
18
+ ```bash
19
+ # Run all tests
20
+ npm test
21
+
22
+ # Watch mode - auto-runs tests on file changes
23
+ npm run test:watch
24
+
25
+ # Filter tests - only runs files containing the filter string
26
+ npm run test:filter=attack # Run attack skill tests
27
+ npm run test:filter=level # Run level-related tests
28
+ npm run test:filter=skill # Run skill tests
29
+
30
+ # Coverage report
31
+ npm run test:coverage
32
+ ```
33
+
34
+ ## Writing Tests
35
+
36
+ ### Basic Test Structure
37
+
38
+ ```javascript
39
+ const { describe, it, beforeEach, afterEach } = require('node:test');
40
+ const assert = require('node:assert');
41
+ const Skill = require('../../lib/skill');
42
+ const { TestHelpers } = require('../utils/test-helpers');
43
+ const { MockOwner } = require('../fixtures/mocks/mock-owner');
44
+
45
+ describe('Skill', () => {
46
+ let mockOwner;
47
+
48
+ beforeEach(() => {
49
+ mockOwner = new MockOwner();
50
+ TestHelpers.clearEventListeners();
51
+ });
52
+
53
+ afterEach(() => {
54
+ TestHelpers.clearEventListeners();
55
+ });
56
+
57
+ describe('Constructor', () => {
58
+ it('should initialize with basic properties', () => {
59
+ let skill = new Skill({key: 'test', owner: mockOwner});
60
+ assert.strictEqual(skill.key, 'test');
61
+ });
62
+ });
63
+ });
64
+ ```
65
+
66
+ ### Using Test Helpers
67
+
68
+ ```javascript
69
+ const { TestHelpers } = require('../utils/test-helpers');
70
+
71
+ // Create mock owner
72
+ let owner = TestHelpers.createMockOwner('owner-1');
73
+
74
+ // Create mock target
75
+ let target = TestHelpers.createMockTarget('target-1');
76
+
77
+ // Create mock client for server tests
78
+ let client = TestHelpers.createMockClient();
79
+
80
+ // Clear event listeners (important in beforeEach and afterEach)
81
+ TestHelpers.clearEventListeners();
82
+
83
+ // Wait for condition
84
+ await TestHelpers.waitForCondition(() => skill.canActivate, 1500);
85
+
86
+ // Sleep for specific time
87
+ await TestHelpers.sleep(100);
88
+ ```
89
+
90
+ ### Using Fixtures
91
+
92
+ ```javascript
93
+ const { BaseSkillsFixtures } = require('../fixtures/skills/base-skills');
94
+ const { BaseLevelsFixtures } = require('../fixtures/levels/base-levels');
95
+
96
+ // Use predefined skill data
97
+ let skillData = {...BaseSkillsFixtures.attackSkill, owner: mockOwner};
98
+ let skill = new Attack(skillData);
99
+
100
+ // Create level with modifiers
101
+ let level = BaseLevelsFixtures.createLevelWithModifiers(5, 500);
102
+
103
+ // Get complete level set
104
+ let levels = BaseLevelsFixtures.createLevelSet();
105
+ ```
106
+
107
+ ### Testing Async Methods
108
+
109
+ ```javascript
110
+ it('should execute skill successfully', async () => {
111
+ let skill = new Skill({key: 'test', owner: mockOwner});
112
+ let result = await skill.execute(mockTarget);
113
+ assert.strictEqual(result, true);
114
+ });
115
+ ```
116
+
117
+ ### Testing Events
118
+
119
+ ```javascript
120
+ it('should fire LEVEL_UP event', async () => {
121
+ let eventFired = false;
122
+ let eventData = null;
123
+
124
+ levelsSet.listenEvent(SkillsEvents.LEVEL_UP, (data) => {
125
+ eventFired = true;
126
+ eventData = data;
127
+ }, 'test-listener');
128
+
129
+ await levelsSet.levelUp();
130
+
131
+ assert.strictEqual(eventFired, true);
132
+ assert.ok(eventData);
133
+ });
134
+ ```
135
+
136
+ ### Testing Error Conditions
137
+
138
+ ```javascript
139
+ it('should return false when skill is not ready', () => {
140
+ let skill = new Skill({owner: mockOwner}); // Missing key
141
+ let result = skill.validate();
142
+ assert.strictEqual(result, false);
143
+ assert.strictEqual(skill.isReady, false);
144
+ });
145
+ ```
146
+
147
+ ## Mock Objects
148
+
149
+ ### MockOwner
150
+
151
+ Simulates a skill owner (player, NPC, etc.):
152
+
153
+ ```javascript
154
+ const { MockOwner } = require('../fixtures/mocks/mock-owner');
155
+
156
+ let owner = new MockOwner('player-1', {x: 100, y: 100});
157
+ owner.stats.atk = 20;
158
+ owner.updateStat('hp', 80);
159
+ owner.setPosition(150, 150);
160
+ ```
161
+
162
+ Properties:
163
+ - `id`: Owner identifier
164
+ - `position`: {x, y} coordinates
165
+ - `stats`: Object with atk, def, hp, mp, aim, dodge, stamina
166
+ - `isCasting`: Boolean casting state
167
+ - `castingTimer`: Timer reference
168
+ - `currentSkills`: Object of available skills
169
+ - `events`: EventsManagerSingleton
170
+ - `eventsPrefix`: Event namespace
171
+
172
+ ### MockTarget
173
+
174
+ Simulates a skill target:
175
+
176
+ ```javascript
177
+ const { MockTarget } = require('../fixtures/mocks/mock-target');
178
+
179
+ let target = new MockTarget('enemy-1', {x: 110, y: 110});
180
+ target.stats.hp = 50;
181
+ target.setPosition(120, 120);
182
+ ```
183
+
184
+ Properties:
185
+ - `id`: Target identifier
186
+ - `position`: {x, y} coordinates
187
+ - `stats`: Object with atk, def, hp, mp, aim, dodge, stamina
188
+
189
+ ### MockClient
190
+
191
+ Simulates a client connection for server-side tests:
192
+
193
+ ```javascript
194
+ const { MockClient } = require('../fixtures/mocks/mock-client');
195
+
196
+ let client = new MockClient();
197
+ sender.send({act: 'test', data: 'value'});
198
+ sender.broadcast({act: 'test', data: 'value'});
199
+
200
+ assert.strictEqual(client.sentMessages.length, 1);
201
+ assert.strictEqual(client.broadcastMessages.length, 1);
202
+
203
+ let lastMsg = client.getLastSentMessage();
204
+ client.clearMessages();
205
+ ```
206
+
207
+ ## Assertions
208
+
209
+ Common assertion patterns:
210
+
211
+ ```javascript
212
+ // Equality
213
+ assert.strictEqual(skill.key, 'test-skill');
214
+ assert.deepStrictEqual(obj1, obj2);
215
+
216
+ // Truthiness
217
+ assert.ok(skill.isReady);
218
+ assert.ok(!skill.canActivate);
219
+
220
+ // Type checking
221
+ assert.strictEqual(typeof skill.key, 'string');
222
+
223
+ // Array/Object checks
224
+ assert.ok(Array.isArray(skill.ownerConditions));
225
+ assert.strictEqual(modifiers.length, 2);
226
+
227
+ // Comparison
228
+ assert.ok(damage > 0);
229
+ assert.ok(newHp < initialHp);
230
+ ```
231
+
232
+ ## Best Practices
233
+
234
+ 1. **Always clear event listeners** in `beforeEach` and `afterEach` to prevent test interference
235
+ 2. **Use fixtures** for complex test data instead of creating inline
236
+ 3. **Test edge cases**: null/undefined inputs, boundary values, error states
237
+ 4. **Test async properly**: Always use `async/await` for async methods
238
+ 5. **One assertion per test** when possible for clarity
239
+ 6. **Descriptive test names**: Use clear, action-oriented descriptions
240
+ 7. **Mock external dependencies**: Don't rely on external systems in unit tests
241
+ 8. **Test events**: Verify events are fired with correct data
242
+ 9. **Test state changes**: Verify object state before and after operations
243
+ 10. **Use beforeEach**: Set up fresh state for each test
244
+
245
+ ## Test File Naming
246
+
247
+ All test files must:
248
+ - Start with `test-` prefix
249
+ - End with `.js` extension
250
+ - Be located in `tests/unit/` or subdirectories
251
+ - Match the source file they're testing
252
+
253
+ Examples:
254
+ - `lib/skill.js` → `tests/unit/test-skill.js`
255
+ - `lib/types/attack.js` → `tests/unit/types/test-attack.js`
256
+ - `lib/server/sender.js` → `tests/unit/server/test-sender.js`
257
+
258
+ ## Debugging Tests
259
+
260
+ ```bash
261
+ # Run specific test file
262
+ npm run test:filter=skill
263
+
264
+ # Add console.log or debugger in test code
265
+ it('should do something', () => {
266
+ console.log('Debug value:', someValue);
267
+ debugger; // Use with --inspect flag
268
+ assert.ok(true);
269
+ });
270
+
271
+ # Run with Node debugger
272
+ node --inspect tests/run-tests.js --filter=skill
273
+ ```
274
+
275
+ ## Common Patterns
276
+
277
+ ### Testing with Modifiers
278
+
279
+ ```javascript
280
+ const { Modifier, ModifierConst } = require('@reldens/modifiers');
281
+
282
+ let modifier = new Modifier({
283
+ key: 'hp-boost',
284
+ propertyKey: 'stats/hp',
285
+ operation: ModifierConst.OPS.INC,
286
+ value: 10
287
+ });
288
+
289
+ // Test modifier application
290
+ modifier.apply(mockOwner);
291
+ assert.strictEqual(mockOwner.stats.hp, 110);
292
+
293
+ // Test modifier reversion
294
+ modifier.revert(mockOwner);
295
+ assert.strictEqual(mockOwner.stats.hp, 100);
296
+ ```
297
+
298
+ ### Testing with Conditions
299
+
300
+ ```javascript
301
+ const { Condition } = require('@reldens/modifiers');
302
+
303
+ let condition = new Condition({
304
+ key: 'hp-check',
305
+ propertyKey: 'stats/hp',
306
+ conditional: 'gt',
307
+ value: 50
308
+ });
309
+
310
+ assert.strictEqual(condition.isValidOn(mockOwner), true);
311
+ ```
312
+
313
+ ### Testing Range Validation
314
+
315
+ ```javascript
316
+ it('should validate range correctly', () => {
317
+ let skill = new Skill({
318
+ key: 'test',
319
+ owner: mockOwner,
320
+ range: 50
321
+ });
322
+
323
+ // In range
324
+ let inRange = skill.isInRange(
325
+ {x: 100, y: 100},
326
+ {x: 110, y: 110}
327
+ );
328
+ assert.strictEqual(inRange, true);
329
+
330
+ // Out of range
331
+ let outOfRange = skill.isInRange(
332
+ {x: 0, y: 0},
333
+ {x: 1000, y: 1000}
334
+ );
335
+ assert.strictEqual(outOfRange, false);
336
+ });
337
+ ```
338
+
339
+ ## Coverage
340
+
341
+ Generate coverage reports to identify untested code:
342
+
343
+ ```bash
344
+ npm run test:coverage
345
+ ```
346
+
347
+ Coverage reports show:
348
+ - Line coverage: Percentage of code lines executed
349
+ - Branch coverage: Percentage of conditional branches tested
350
+ - Function coverage: Percentage of functions called
351
+ - Statement coverage: Percentage of statements executed
352
+
353
+ Aim for:
354
+ - Minimum 80% overall coverage
355
+ - 100% coverage for critical paths (damage calculation, level progression)
356
+ - All error paths tested