---
name: gpui-test
description: Writing tests for GPUI applications. Use when testing components, async operations, or UI behavior.
---

## Overview

GPUI provides a comprehensive testing framework that allows you to test UI components, async operations, and distributed systems. Tests run on a single-threaded executor that provides deterministic execution and the ability to test complex async scenarios. GPUI tests use the `#[gpui::test]` attribute and work with `TestAppContext` for basic testing and `VisualTestContext` for window-dependent tests.

### Rules

- If test does not require windows or rendering, we can avoid use `[gpui::test]` and `TestAppContext`, just write simple rust test.

## Core Testing Infrastructure

### Test Attributes

#### Basic Test

```rust
#[gpui::test]
fn my_test(cx: &mut TestAppContext) {
    // Test implementation
}
```

#### Async Test

```rust
#[gpui::test]
async fn my_async_test(cx: &mut TestAppContext) {
    // Async test implementation
}
```

#### Property Test with Iterations

```rust
#[gpui::test(iterations = 10)]
fn my_property_test(cx: &mut TestAppContext, mut rng: StdRng) {
    // Property testing with random data
}
```

### Test Contexts

#### TestAppContext

`TestAppContext` provides access to GPUI's core functionality without windows:

```rust
#[gpui::test]
fn test_entity_operations(cx: &mut TestAppContext) {
    // Create entities
    let entity = cx.new(|cx| MyComponent::new(cx));

    // Update entities
    entity.update(cx, |component, cx| {
        component.value = 42;
        cx.notify();
    });

    // Read entities
    let value = entity.read_with(cx, |component, _| component.value);
    assert_eq!(value, 42);
}
```

#### VisualTestContext

`VisualTestContext` extends `TestAppContext` with window support:

```rust
#[gpui::test]
fn test_with_window(cx: &mut TestAppContext) {
    // Create window with component
    let window = cx.update(|cx| {
        cx.open_window(Default::default(), |_, cx| {
            cx.new(|cx| MyComponent::new(cx))
        }).unwrap()
    });

    // Convert to visual context
    let mut cx = VisualTestContext::from_window(window.into(), cx);

    // Access window and component
    let component = window.root(&mut cx).unwrap();
}
```

## Additional Resources

- For detailed testing patterns and examples, see [reference.md](reference.md)
- For best practices and running tests, see [examples.md](examples.md)