test_executors 0.3.4

Simple async executors for testing.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

test_executors is a Rust crate that provides simple async executors primarily for testing purposes. It offers three main executors (spin_on, sleep_on, spawn_on) and integrates with the some_executor ecosystem.

## Common Development Commands

### Building the Project
```bash
cargo build
```

### Running Tests
```bash
# Run all tests
cargo test

# Run a specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run WASM tests (requires wasm-pack)
wasm-pack test --browser
```

### Checking Code
```bash
# Type check
cargo check

# Format code
cargo fmt

# Lint code
cargo clippy
```

## Architecture Overview

The crate is organized into several key modules:

1. **Core Executors** (src/lib.rs):
   - `spin_on`: Busy-loop executor for minimal latency
   - `sleep_on`: Condition variable-based executor for CPU efficiency
   - `spawn_on`: Thread-spawning executor for parallel execution

2. **Runtime Module** (src/aruntime.rs):
   - Provides `SpinRuntime`, `SleepRuntime`, and `SpawnRuntime`
   - Implements the `some_executor::SomeExecutor` trait for integration with the some_executor ecosystem
   - Allows setting a global executor via `set_global_test_runtime()`

3. **Utility Modules**:
   - `noop_waker.rs`: Provides a no-op waker for testing
   - `pend_forever.rs`: A future that never completes (useful for testing)
   - `sys.rs`: Platform-specific time abstractions

4. **Proc Macro** (test_executors_proc/):
   - Provides the `#[async_test]` attribute macro
   - Automatically adapts tests for both native and WASM targets

## Key Design Decisions

- **Platform Support**: Special handling for WASM targets throughout the codebase, using `wasm-bindgen-futures` for browser integration
- **Executor Choice**: Each executor serves different use cases - spin for latency, sleep for efficiency, spawn for parallelism
- **some_executor Integration**: All runtimes implement the SomeExecutor trait to work with executor-agnostic code
- **Testing Focus**: The crate is designed specifically for testing async code without heavyweight runtime dependencies

## Dependencies

- `some_executor`: For executor-agnostic trait implementations
- `logwise`: For structured logging
- `blocking_semaphore`: For the sleep_on executor's synchronization
- WASM-specific: `wasm-bindgen`, `web-time`, `wasm-bindgen-futures` (only on wasm32 targets)