# Godot Testability Runtime
**Embedded Godot runtime for comprehensive Rust testing** - inspired by SwiftGodot's testability framework.
[](https://discord.gg/gqkeBsH93H)
[](https://crates.io/crates/godot-testability-runtime)
[](https://docs.rs/godot-testability-runtime)
[](LICENSE-MIT)
## 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`:
```toml
[dev-dependencies]
godot-testability-runtime = "0.1"
```
Write your first embedded test using standard Rust `#[test]` functions:
```rust
// 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
```rust
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:
```yaml
# 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](https://github.com/migueldeicaza/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](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](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!** 🦀🎮