Godot Testability Runtime

Embedded Godot runtime for comprehensive Rust testing - inspired by SwiftGodot's testability framework.

Overview

This crate provides the ability to run tests within a real Godot runtime environment, giving you access to the full Godot engine API for comprehensive testing. It's inspired by SwiftGodot's successful embedded testing approach and brings the same capabilities to the Rust ecosystem.

Unlike traditional unit tests that mock or simulate engine behavior, this framework runs your tests inside an actual Godot instance, allowing you to test:

• Scene tree manipulation
• Node lifecycle and signals
• Physics and rendering systems
• Resource loading and management
• Custom Godot classes and scripts
• Engine integration edge cases

Key Features

• ✅ Real Embedded Runtime: Actual Godot engine running in-process via libgodot
• ✅ Synchronous Testing: Simple, straightforward test execution using standard Rust #[test] functions
• ✅ Memory Safe: Proper Rust safety around all FFI interactions
• ✅ Cross-Platform Ready: Works on macOS now, Linux/Windows when libgodot is available
• ✅ CI/CD Friendly: Headless mode for automated testing environments
• ✅ Framework Agnostic: Works with any Rust Godot project, not just specific frameworks
• ✅ Automatic Dependencies: Downloads libgodot automatically at build time

Quick Start

Add to your Cargo.toml:

[dev-dependencies]
godot-testability-runtime = "0.1"

Write your first embedded test using standard Rust #[test] functions:

// tests/my_godot_tests.rs
use godot_testability_runtime::prelude::*;

// Simple test using the embedded_test_fn! macro
embedded_test_fn!(test_basic_runtime, {
    // This code runs inside a real Godot runtime!
    assert!(GodotRuntime::is_running());
    
    // Test runtime execution
    let result = "Hello Godot!";
    assert_eq!(result, "Hello Godot!");
    
    Ok(())
});

// Test with actual Godot functionality
embedded_test_fn!(test_godot_variants, {
    // Test Godot's Variant system
    let variant = godot::prelude::Variant::from(42);
    assert_eq!(variant.get_type(), godot::prelude::VariantType::INT);
    
    let int_value: i32 = variant.to();
    assert_eq!(int_value, 42);
    
    Ok(())
});

Run with: cargo test

Platform Support

✅ macOS (Current)

• Uses libgodot.dylib from SwiftGodot releases
• Full embedded runtime functionality
• Both arm64 and x86_64 architectures
• Automatically downloads libgodot at build time

🔄 Linux (Future)

• Awaiting libgodot.so availability
• All FFI bindings are platform-ready
• Framework will work immediately when libgodot supports Linux

🔄 Windows (Future)

• Awaiting libgodot.dll availability
• All FFI bindings are platform-ready
• Framework will work immediately when libgodot supports Windows

Advanced Usage

Test Organization

use godot_testability_runtime::prelude::*;

// Organize tests into logical groups using standard Rust test modules
mod scene_tests {
    use super::*;
    
    embedded_test_fn!(test_node_creation, {
        // Test scene tree operations
        // - Node creation and parenting
        // - Scene loading and instantiation
        // - Node lifecycle (ready, tree_entered, etc.)
        assert!(GodotRuntime::is_running());
        Ok(())
    });
    
    embedded_test_fn!(test_scene_loading, {
        // Test scene loading functionality
        assert!(GodotRuntime::is_running());
        Ok(())
    });
}

mod physics_tests {
    use super::*;
    
    embedded_test_fn!(test_physics_bodies, {
        // Test physics body creation and behavior
        assert!(GodotRuntime::is_running());
        Ok(())
    });
}

CI/CD Integration

The framework is designed for automated testing:

# GitHub Actions example
- name: Run Godot Runtime Tests
  run: |
    # macOS runners have libgodot support
    cargo test --release
    # Tests automatically download libgodot at build time

How It Works

libgodot Integration

This crate uses libgodot - a version of Godot built as a library rather than a standalone application. This allows us to:

1. Embed Godot directly in the test process
2. Initialize the full engine including scene tree, physics, rendering
3. Execute tests within the Godot main loop
4. Access all Godot APIs exactly as they work in the real engine

Architecture

┌─────────────────────────────────────┐
│          Your Test Code             │
├─────────────────────────────────────┤
│     Testability Framework          │
│  (This Crate)                      │
├─────────────────────────────────────┤
│         FFI Bindings               │
│  (Rust ↔ libgodot.dylib)          │
├─────────────────────────────────────┤
│        libgodot.dylib              │
│  (Embedded Godot Engine)           │
└─────────────────────────────────────┘

Examples

The tests/ directory contains comprehensive examples:

• main.rs - Complete test suite demonstrating all functionality:
  • Basic runtime initialization and cleanup
  • Godot Variant system testing
  • Signal handling and event processing
  • Memory management and safety
  • Error handling patterns

Run examples: cargo test - All examples run as real tests!

Contributing

This crate is designed to benefit the entire Rust Godot ecosystem. Contributions are welcome!

Priority Areas

1. Linux/Windows Support: Help with libgodot availability on other platforms
2. API Enhancements: More utilities for common testing patterns
3. Performance: Optimizations for test execution speed
4. Documentation: More examples and guides

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Acknowledgments

• SwiftGodot: This framework is directly inspired by SwiftGodot's excellent testability system
• libgodot: Created by the SwiftGodot team to enable embedded Godot runtime
• godot-rust: The foundation that makes Rust + Godot development possible

Bring the power of embedded runtime testing to your Rust Godot projects! 🦀🎮