cat-haven/TESTING.md

Cat Haven - Testing Guide

Overview

Complete automated testing strategy with unit, integration, and end-to-end tests using Busted framework.

Test Structure

test/
├── test_helper.lua          # LOVR mocks and test utilities
├── run_tests.lua            # Test runner with TAP/JUnit reports
├── spec/                    # Unit tests (7 modules)
│   ├── core_spec.lua
│   ├── json_spec.lua
│   ├── voxel_spec.lua
│   ├── cat_spec.lua
│   ├── house_spec.lua
│   ├── ui_spec.lua
│   └── audio_spec.lua
├── integration/             # Integration tests
│   └── game_flow_spec.lua
└── e2e/                     # Edge case & stress tests
    └── edge_cases_spec.lua

Test Coverage

Unit Tests (7 modules, ~180 tests)

JSON Module (test/spec/json_spec.lua)

• String encoding/decoding with escape sequences
• Number encoding/decoding (integers, floats, negative)
• Boolean encoding/decoding
• Array encoding/decoding with nested structures
• Object encoding/decoding with non-string keys
• Null handling
• Round-trip validation (encode → decode → compare)
• Edge cases: NaN, infinity, empty arrays/objects
• Invalid JSON handling
• Non-string key conversion

Voxel Module (test/spec/voxel_spec.lua)

• Texture generation with noise and borders
• Mesh creation with correct vertex data
• Rendering with pass object
• Raycast with furniture and cats
• AABB collision detection
• Edge cases: nil input, empty lists, zero direction

Cat Module (test/spec/cat_spec.lua)

• Cat creation with personality
• AI behavior (seeking furniture)
• Needs update over time
• Sleep state transitions
• Serialization/deserialization
• Pet interaction
• Personality compatibility
• Edge cases: nil personality, zero distance

House Module (test/spec/house_spec.lua)

• Furniture creation and upgrades
• Placement with collision detection
• Grid bounds checking
• Interaction detection
• Serialization round-trip
• Edge cases: out of bounds, overlapping furniture

UI Module (test/spec/ui_spec.lua)

• HUD rendering with happiness meter
• Inventory panel display
• Cat log display
• Placement preview
• Mouse interaction
• Edge cases: nil core, empty lists

Audio Module (test/spec/audio_spec.lua)

• Purr sound generation
• Meow sound generation
• Click sound generation
• Ambient sound generation
• Spatial audio properties
• Sound cloning and playback
• Edge cases: nil position

Core Module (test/spec/core_spec.lua)

• Game state initialization
• Cat spawn with personality
• Furniture addition
• Happiness calculation
• Save/load round-trip
• Cat departure logic
• Pause toggle
• Edge cases: empty cat list, zero cats

Integration Tests (~30 tests)

Game Flow (test/integration/game_flow_spec.lua)

• Full initialization sequence
• Module dependencies resolved
• Audio system loaded
• Voxel textures created
• Initial cats spawned
• Furniture placement
• Module interactions (cat-house, cat-audio, UI-cat, voxel-cat)
• Save/load round-trip
• Complete game state integrity
• Furniture upgrades
• Personality compatibility
• UI interaction

End-to-End Tests (~40 tests)

Edge Cases (test/e2e/edge_cases_spec.lua)

• Empty cat list (0 cats)
• Zero distance between cats
• Nil personality values
• Invalid JSON input
• Max capacity (8 cats)
• Furniture at grid bounds
• Low happiness departure
• Furniture upgrades (3 levels)
• Personality compatibility matrix
• Audio generation without crash
• Serialization with nil fields
• Rapid updates (stress test)
• 25+ furniture items
• Multiple save/load cycles
• Nil core in all modules
• Nil house/ui/voxel/audio modules
• Zero distance in movement
• Nil furniture/cats in raycast

Running Tests

Prerequisites

Install Busted testing framework:

# Install LuaRocks
sudo apt-get update && sudo apt-get install -y luarocks

# Install Busted
luarocks install busted

Run Tests

# Run all tests
lua test/run_tests.lua

# Or with LuaJIT (faster)
luajit test/run_tests.lua

# Run specific test file
lua test/run_tests.lua test/spec/json_spec.lua

# Run with verbose output
lua test/run_tests.lua 2>&1 | tee test-output.txt

Test Output

TAP Format (stdout)

1..180
ok 1 - JSON Module should encode strings
ok 2 - JSON Module should encode numbers
ok 3 - JSON Module should encode booleans
# ... etc

JUnit XML Report (test-report.xml)

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="Cat Haven Tests">
  <testsuite name="Cat Haven" tests="250" failures="0" errors="0">
    <testcase name="JSON Module" classname="test/spec/json_spec.lua"/>
    <!-- ... -->
  </testsuite>
</testsuites>

CI Integration

# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Busted
        run: |
          sudo apt-get update
          sudo apt-get install -y lua5.1 luarocks
          luarocks install busted
      - name: Run tests
        run: lua test/run_tests.lua
      - name: Upload test report
        uses: actions/upload-artifact@v3
        with:
          name: test-report
          path: test-report.xml

Adding New Tests

1. Create test file in appropriate directory:

   • test/spec/ for unit tests
   • test/integration/ for integration tests
   • test/e2e/ for edge case tests

2. Use Busted syntax:

describe('Module Name', function()
  it('should do something', function()
    -- test code
  end)
  
  it('should handle edge case', function()
    -- test code
  end)
end)

3. Use mocks for LOVR API:

local test_helper = require('test.test_helper')
local mocks = test_helper.mocks
local utils = test_helper.utils

before_each(function()
  _G.lovr = mocks.lovr
  require('src.module')
end)

Test Statistics

• Total test files: 11
• Unit tests: ~180 assertions
• Integration tests: ~30 assertions
• End-to-end tests: ~40 assertions
• Total test cases: 250+
• Coverage: All modules, all functions, all edge cases

Mocks

LOVR Graphics

• newImage, newTexture, newMesh, newMaterial, newModel
• box, text

LOVR Audio

• newSource with spatial properties

LOVR System

• getWindowDimensions, getMousePosition

LOVR Filesystem

• newFile for save/load testing

Test Utilities

• assertDeepEqual for table comparison
• createMockPass for rendering tests
• createMockCat for cat creation
• createMockFurniture for furniture creation
• setupFilesystem for save/load testing

Test Helper API

Mocks

local mocks = require('test.test_helper').mocks

-- Setup mock filesystem
mocks.setupFilesystem(saveData)

-- Reset mocks
mocks.reset()

Utilities

local utils = require('test.test_helper').utils

-- Deep table comparison
utils.assertDeepEqual(actual, expected, msg)

-- Create mock render pass
local pass = utils.createMockPass()

-- Create mock cat
local cat = utils.createMockCat({ overrides })

-- Create mock furniture
local furn = utils.createMockFurniture({ overrides })