Cursor rule

1---
2paths:
3  - "**/*.rs"
4---
5# Rust Testing
6 
7> This file extends [common/testing.md](../common/testing.md) with Rust-specific content.
8 
9## Test Framework
10 
11- **`#[test]`** with `#[cfg(test)]` modules for unit tests
12- **rstest** for parameterized tests and fixtures
13- **proptest** for property-based testing
14- **mockall** for trait-based mocking
15- **`#[tokio::test]`** for async tests
16 
17## Test Organization
18 
19```text
20my_crate/
21├── src/
22│   ├── lib.rs           # Unit tests in #[cfg(test)] modules
23│   ├── auth/
24│   │   └── mod.rs       # #[cfg(test)] mod tests { ... }
25│   └── orders/
26│       └── service.rs   # #[cfg(test)] mod tests { ... }
27├── tests/               # Integration tests (each file = separate binary)
28│   ├── api_test.rs
29│   ├── db_test.rs
30│   └── common/          # Shared test utilities
31│       └── mod.rs
32└── benches/             # Criterion benchmarks
33    └── benchmark.rs
34```
35 
36Unit tests go inside `#[cfg(test)]` modules in the same file. Integration tests go in `tests/`.
37 
38## Unit Test Pattern
39 
40```rust
41#[cfg(test)]
42mod tests {
43    use super::*;
44 
45    #[test]
46    fn creates_user_with_valid_email() {
47        let user = User::new("Alice", "alice@example.com").unwrap();
48        assert_eq!(user.name, "Alice");
49    }
50 
51    #[test]
52    fn rejects_invalid_email() {
53        let result = User::new("Bob", "not-an-email");
54        assert!(result.is_err());
55        assert!(result.unwrap_err().to_string().contains("invalid email"));
56    }
57}
58```
59 
60## Parameterized Tests
61 
62```rust
63use rstest::rstest;
64 
65#[rstest]
66#[case("hello", 5)]
67#[case("", 0)]
68#[case("rust", 4)]
69fn test_string_length(#[case] input: &str, #[case] expected: usize) {
70    assert_eq!(input.len(), expected);
71}
72```
73 
74## Async Tests
75 
76```rust
77#[tokio::test]
78async fn fetches_data_successfully() {
79    let client = TestClient::new().await;
80    let result = client.get("/data").await;
81    assert!(result.is_ok());
82}
83```
84 
85## Mocking with mockall
86 
87Define traits in production code; generate mocks in test modules:
88 
89```rust
90// Production trait — pub so integration tests can import it
91pub trait UserRepository {
92    fn find_by_id(&self, id: u64) -> Option<User>;
93}
94 
95#[cfg(test)]
96mod tests {
97    use super::*;
98    use mockall::predicate::eq;
99 
100    mockall::mock! {
101        pub Repo {}
102        impl UserRepository for Repo {
103            fn find_by_id(&self, id: u64) -> Option<User>;
104        }
105    }
106 
107    #[test]
108    fn service_returns_user_when_found() {
109        let mut mock = MockRepo::new();
110        mock.expect_find_by_id()
111            .with(eq(42))
112            .times(1)
113            .returning(|_| Some(User { id: 42, name: "Alice".into() }));
114 
115        let service = UserService::new(Box::new(mock));
116        let user = service.get_user(42).unwrap();
117        assert_eq!(user.name, "Alice");
118    }
119}
120```
121 
122## Test Naming
123 
124Use descriptive names that explain the scenario:
125- `creates_user_with_valid_email()`
126- `rejects_order_when_insufficient_stock()`
127- `returns_none_when_not_found()`
128 
129## Coverage
130 
131- Target 80%+ line coverage
132- Use **cargo-llvm-cov** for coverage reporting
133- Focus on business logic — exclude generated code and FFI bindings
134 
135```bash
136cargo llvm-cov                       # Summary
137cargo llvm-cov --html                # HTML report
138cargo llvm-cov --fail-under-lines 80 # Fail if below threshold
139```
140 
141## Testing Commands
142 
143```bash
144cargo test                       # Run all tests
145cargo test -- --nocapture        # Show println output
146cargo test test_name             # Run tests matching pattern
147cargo test --lib                 # Unit tests only
148cargo test --test api_test       # Specific integration test (tests/api_test.rs)
149cargo test --doc                 # Doc tests only
150```
151 
152## References
153 
154See skill: `rust-testing` for comprehensive testing patterns including property-based testing, fixtures, and benchmarking with Criterion.
155