Integration Testing

Patterns and conventions for writing integration tests in GoudEngine, covering cross-module interactions, GL context management, and FFI boundary testing.

When to Use

Use when writing tests that exercise multiple modules together, test FFI boundaries end-to-end, or validate SDK wrappers against the Rust core.

Test Organization

goud_engine/
├── src/
│   ├── ecs/
│   │   └── mod.rs          # Unit tests in #[cfg(test)] module
│   ├── ffi/
│   │   └── mod.rs          # Unit tests for FFI functions
│   └── libs/graphics/
│       └── mod.rs          # Unit tests (may need GL context)
├── tests/                   # Integration tests
│   ├── ecs_integration.rs
│   ├── ffi_integration.rs
│   └── graphics_integration.rs
└── benches/                 # Benchmarks (criterion)
    └── ecs_bench.rs

sdks/
├── csharp.tests/            # C# SDK tests (xUnit)
└── python/
    └── test_bindings.py     # Python SDK tests

GL Context Management

Many graphics tests require an OpenGL context. Use the helper:

rust
1use crate::test_helpers::init_test_context;
2
3#[test]
4fn test_renderer_initialization() {
5    let _ctx = init_test_context();
6    // GL-dependent test code here
7}

Rules:

• Tests that need GL MUST call init_test_context() at the start
• Tests that do NOT need GL (math, ECS logic, data structures) MUST NOT call it
• GL tests may fail in CI environments without a display — mark test expectations accordingly

Test Factory Patterns

Create reusable factories for common test objects:

rust
1#[cfg(test)]
2mod test_helpers {
3    use super::*;
4
5    pub fn create_test_entity(world: &mut World) -> Entity {
6        let entity = world.spawn();
7        world.add_component(entity, Transform2D::default());
8        entity
9    }
10
11    pub fn create_test_sprite(world: &mut World, entity: Entity) {
12        world.add_component(entity, Sprite::new("test_texture"));
13    }
14}

FFI Integration Testing

Test the full path: Rust → FFI → SDK wrapper.

rust
1#[test]
2fn test_ffi_create_entity_roundtrip() {
3    // 1. Create context via FFI
4    let ctx = unsafe { ffi::create_context() };
5    assert!(!ctx.is_null());
6
7    // 2. Create entity via FFI
8    let entity_id = unsafe { ffi::create_entity(ctx) };
9    assert!(entity_id > 0);
10
11    // 3. Clean up
12    unsafe { ffi::destroy_context(ctx) };
13}

FFI test rules:

• Always test null pointer handling (pass null, expect error code)
• Test memory lifecycle (create → use → destroy)
• Verify error codes match expected values
• Test string marshaling (CStr roundtrips)

Cross-SDK Parity Tests

Verify the same operation produces the same result in both SDKs:

1. Write the test in Rust (ground truth)
2. Write equivalent test in Python (test_bindings.py)
3. Write equivalent test in C# (csharp.tests/)
4. Results must match across all three

Test Categories

Checklist

Before submitting integration tests:

• Tests are in the correct location (unit vs integration)
• GL-dependent tests use init_test_context()
• Non-GL tests verified to run without display
• FFI tests check null pointer cases
• FFI tests verify memory cleanup
• Test names describe the scenario being tested
• No #[ignore] or todo!() in test code
• Arrange-Act-Assert pattern followed