test_executors 0.3.5

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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# 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
cargo build --release
```

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

# Run a specific test
cargo test test_name

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

# Run tests without stopping on failure
cargo test --no-fail-fast

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

# Run WASM tests with Chrome specifically
wasm-pack test --chrome
```

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

# Format code
cargo fmt

# Check formatting without applying changes
cargo fmt --check

# Lint code
cargo clippy

# Lint with no dependencies warnings
cargo clippy --no-deps

# Generate documentation
cargo doc

# Generate and open documentation in browser
cargo doc --open
```

## Architecture Overview

The crate consists of two packages:

### Main Crate (`test_executors`)
Located in the root directory, this provides the core functionality:

1. **Core Executors** (src/lib.rs):
   - `spin_on`: Busy-loop executor for minimal latency, uses 100% CPU
   - `sleep_on`: Condition variable-based executor using blocking_semaphore for CPU efficiency
   - `spawn_on`: Thread-spawning executor for parallel execution on new OS thread

2. **Runtime Module** (src/aruntime.rs):
   - Provides `SpinRuntime`, `SleepRuntime`, and `SpawnRuntime` structs
   - Implements the `some_executor::SomeExecutor` trait for all runtimes
   - Global executor management via `set_global_test_runtime()` and `get_test_runtime()`
   - Each runtime wraps its corresponding executor for trait-based usage

3. **Utility Modules**:
   - `noop_waker.rs`: Provides a no-op waker that does nothing when wake() is called
   - `pend_forever.rs`: A future that never completes (useful for testing executor behavior)
   - `sys.rs`: Platform-specific time abstractions (different implementations for native vs WASM)

### Proc Macro Crate (`test_executors_proc`)
Located in test_executors_proc/, provides the `#[async_test]` attribute macro:
- On native platforms: Wraps test in `sleep_on` executor
- On WASM targets: Uses `wasm_bindgen_test` for browser integration
- Automatically handles platform differences transparently

## Key Design Decisions

- **Waker Implementation**: `spin_on` uses a no-op waker, while `sleep_on` uses a semaphore-based waker for efficient blocking
- **Platform Abstraction**: `spawn_local` automatically chooses between native thread blocking and WASM event loop integration
- **Logging Context**: All executors preserve logwise context across async boundaries using `logwise::context::Context`
- **some_executor Integration**: All runtimes implement the SomeExecutor trait to enable executor-agnostic async code
- **Testing Focus**: Designed for unit tests without heavyweight runtime dependencies like tokio

## CI/CD Pipeline

The project uses GitHub Actions (`.github/workflows/ci.yaml`) with the following checks:
- `cargo fmt --check` - Enforces code formatting
- `cargo check` - Type checking
- `cargo clippy --no-deps` - Linting without dependency warnings
- `cargo doc` - Documentation generation
- `cargo test` - Test execution

All warnings are treated as errors via `RUSTFLAGS="-D warnings"`