Spell Testing Guide

Comprehensive guide for testing spells in OpenRoads to ensure they work correctly and are properly balanced.

🎯 Testing Overview

Proper spell testing ensures:

• Functionality - Spells work as intended

• Balance - Spells are fair and fun

• Stability - No crashes or errors

• User Experience - Clear feedback and intuitive behavior

📋 Testing Checklist

✅ Basic Functionality

• Spell loads without errors

• Spell appears in spell list

• Spell can be cast successfully

• All effects trigger correctly

• Messages display properly

• Cooldowns work as expected

✅ Validation Testing

• Element requirements enforced

• Level requirements enforced

• SP cost deducted correctly

• Required items consumed

• Target validation works

• Restriction enforcement

✅ Edge Cases

• Insufficient SP handling

• Invalid targets

• Interrupted casting

• Multiple simultaneous casts

• Boundary conditions

• Error recovery

✅ Balance Testing

• Damage/healing amounts appropriate

• SP costs reasonable

• Cooldowns prevent spam

• Power level matches requirements

• Progression feels smooth

🛠️ Testing Environment Setup

Test Character Creation

Create characters with different configurations:

# Low-level character
test_char_low:
  spell_level: 5
  phys_level: 3
  element: "fire"
  sp: 50

# Mid-level character  
test_char_mid:
  spell_level: 15
  phys_level: 10
  element: "water"
  sp: 150

# High-level character
test_char_high:
  spell_level: 30
  phys_level: 25
  element: "air"
  sp: 300

Test Rooms

Use different room types:

• Safe rooms - For non-combat testing

• Combat rooms - With enemies for damage testing

• Restricted rooms - For location restriction testing

• Empty rooms - For summoning testing

Test Items

Prepare test items:

• Required items - For spells with item requirements

• Consumables - To test item consumption

• Equipment - To test stat interactions

🧪 Testing Procedures

1. Syntax and Loading Tests

Check YAML Syntax:

# Validate YAML syntax online or with tools
yamllint spells/custom/your_spell.yaml

Test Loading:

1. Start server

2. Check logs for loading errors

3. Verify spell appears in spell list

4. Use spells command to see spell details

Common Loading Issues:

• Invalid YAML syntax

• Missing required properties

• Invalid property values

• Incorrect file location

2. Basic Casting Tests

Successful Cast Test:

1. Meet all requirements (level, element, SP, items)

2. Cast spell with valid target

3. Verify effects occur

4. Check SP deduction

5. Confirm cooldown starts

Requirement Failure Tests:

1. Test with wrong element

2. Test with insufficient level

3. Test with insufficient SP

4. Test without required items

5. Test with invalid target

3. Effect Testing

Damage Effects:

# Test spell
name: "Test Fireball"
effects:
  - type: "damage"
    damage_min: 20
    damage_max: 30
    damage_type: "fire"

Test Procedure:

1. Cast on enemy with known HP

2. Verify damage is within range

3. Check enemy HP reduction

4. Test multiple casts for variance

5. Verify enemy death at 0 HP

Healing Effects:

# Test spell
name: "Test Heal"
effects:
  - type: "heal"
    heal_min: 15
    heal_max: 25

Test Procedure:

1. Reduce character HP

2. Cast healing spell

3. Verify HP increase within range

4. Test healing cap at max HP

5. Test multiple casts

Teleportation Effects:

# Test spell
name: "Test Teleport"
effects:
  - type: "teleport"
    teleport:
      element_room: true

Test Procedure:

1. Note starting location

2. Cast teleport spell

3. Verify arrival at correct location

4. Test with different elements

5. Test invalid room handling

4. Timing Tests

Cast Time Testing:

name: "Test Slow Spell"
cast_time: 5

Test Procedure:

1. Start casting

2. Verify "cast start" message

3. Wait for completion

4. Verify "cast complete" message

5. Test interruption (move/damage)

Cooldown Testing:

name: "Test Cooldown Spell"
cooldown: 10

Test Procedure:

1. Cast spell successfully

2. Try to cast again immediately

3. Verify cooldown message

4. Wait for cooldown to expire

5. Verify spell can be cast again

5. Restriction Testing

Combat Restrictions:

restrictions:
  combat_only: true

Test Procedure:

1. Try casting outside combat (should fail)

2. Enter combat

3. Cast spell (should succeed)

4. Test non_combat_only restriction

Location Restrictions:

restrictions:
  required_rooms: ["1", "2"]
  forbidden_rooms: ["10"]

Test Procedure:

1. Test in required room (should work)

2. Test in forbidden room (should fail)

3. Test in neutral room (depends on required_rooms)

6. Message Testing

Test All Message Types:

messages:
  success: "Test success: %s"
  failure_level: "Need level %d (you're %d)"
  cast_start: "Beginning test cast..."

Test Procedure:

1. Trigger each message condition

2. Verify correct message displays

3. Check placeholder substitution

4. Test message formatting

📊 Balance Testing

Damage Balance Tests

Damage Per SP Analysis:

Test Results:
Spell: Fireball
- Damage Range: 20-35 (avg 27.5)
- SP Cost: 15
- Damage per SP: 1.83
- Comparison: Similar level spells should be 1.5-2.0

DPS Testing:

Test Results:
Spell: Lightning Bolt
- Damage: 25-40 (avg 32.5)
- Cooldown: 4 seconds
- DPS: 8.125
- SP per second: 4.5 (18 SP / 4 sec)

Healing Balance Tests

Healing Efficiency:

Test Results:
Spell: Greater Heal
- Healing: 40-60 (avg 50)
- SP Cost: 25
- Healing per SP: 2.0
- Cast Time: 3 seconds
- Healing per second: 16.67

Utility Balance Tests

Teleportation Costs:

• Short range (same area): 10-20 SP

• Medium range (different area): 20-40 SP

• Long range (anywhere): 40+ SP

• Emergency escape: Higher cost justified

🐛 Common Issues and Solutions

Loading Issues

Spell Not Loading:

• Check file location (spells/custom/)

• Verify YAML syntax

• Check server logs for errors

• Ensure file has .yaml extension

Spell Not Appearing:

• Check spell name conflicts

• Verify required properties present

• Check for validation errors

• Restart server if needed

Casting Issues

Spell Won't Cast:

• Verify all requirements met

• Check target type and arguments

• Ensure sufficient SP

• Check for active cooldowns

Effects Not Working:

• Verify effect syntax

• Check effect type spelling

• Ensure target is valid

• Check for restriction conflicts

Balance Issues

Spell Too Powerful:

• Increase SP cost

• Add cooldown

• Reduce damage/healing

• Add restrictions

Spell Too Weak:

• Reduce SP cost

• Reduce cooldown

• Increase effects

• Remove unnecessary restrictions

📈 Performance Testing

Load Testing

1. Cast spell repeatedly

2. Monitor server performance

3. Check for memory leaks

4. Verify cleanup occurs

Concurrency Testing

1. Multiple players cast simultaneously

2. Test cooldown isolation

3. Verify effect independence

4. Check for race conditions

Stress Testing

1. Cast many spells quickly

2. Test with maximum effects

3. Monitor resource usage

4. Verify graceful degradation

📝 Documentation Testing

Message Clarity

• Are success messages clear?

• Do failure messages explain why?

• Are placeholders working correctly?

• Is the description accurate?

Help Integration

• Does spell appear in spells command?

• Are requirements clearly shown?

• Is usage format correct?

• Are examples helpful?

🎯 Automated Testing

Test Scripts

Create test scripts for common scenarios:

#!/bin/bash
# Basic spell test script
echo "Testing spell loading..."
# Add test commands here

echo "Testing spell casting..."
# Add casting tests here

echo "Testing spell effects..."
# Add effect verification here

Regression Testing

• Test existing spells after changes

• Verify backward compatibility

• Check for unintended side effects

• Maintain test spell library

📊 Test Results Documentation

Test Report Template

Spell: [Spell Name]
Date: [Test Date]
Tester: [Your Name]

Functionality Tests:
✅ Loading: Pass
✅ Casting: Pass
✅ Effects: Pass
⚠️ Messages: Minor formatting issue

Balance Tests:
✅ Damage/SP ratio: 1.8 (target: 1.5-2.0)
✅ Cooldown: Appropriate
❌ Level requirement: Too low for power

Issues Found:
1. Success message missing target placeholder
2. Minimum level should be 12, not 8

Recommendations:
1. Fix message formatting
2. Increase min_spell_level to 12
3. Retest after changes

🎓 Best Practices

Testing Workflow

1. Plan - Define what to test

2. Prepare - Set up test environment

3. Execute - Run systematic tests

4. Document - Record results and issues

5. Iterate - Fix issues and retest

Collaboration

• Share test results with team

• Use consistent testing procedures

• Document known issues

• Coordinate testing efforts

Continuous Testing

• Test after every change

• Maintain test spell collection

• Regular balance reviews

• Player feedback integration

🎉 Conclusion

Thorough testing ensures spells are functional, balanced, and enjoyable. Take time to test systematically and document results for future reference.

Next Steps

1. Spell Design Guidelines - Design principles

2. Spell Balance Guide - Balance considerations

3. YAML Spell Tutorial - Implementation guide

4. Start Testing - Apply these procedures to your spells!

Remember: Good testing leads to great spells that players love to use! ✨