agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/test-mock-traits.md

@@ -1,189 +0,0 @@
-# test-mock-traits
-
-> Use traits for dependencies to enable mocking in tests
-
-## Why It Matters
-
-Concrete dependencies make testing hard—you can't easily test error paths, timeouts, or edge cases without real external systems. Extracting dependencies behind traits lets you inject test doubles (mocks, fakes, stubs), enabling isolated unit tests that run fast and cover edge cases.
-
-## Bad
-
-```rust
-struct UserService {
-    db: PostgresConnection,  // Concrete type - hard to test
-}
-
-impl UserService {
-    async fn get_user(&self, id: u64) -> Result<User, Error> {
-        // Directly calls Postgres - needs real database to test
-        self.db.query("SELECT * FROM users WHERE id = $1", &[&id]).await
-    }
-}
-
-// Test requires real Postgres instance
-#[tokio::test]
-async fn test_get_user() {
-    let db = PostgresConnection::connect("postgres://...").await?;
-    let service = UserService { db };
-    // Slow, flaky, can't test error paths
-}
-```
-
-## Good
-
-```rust
-// Define trait for dependency
-#[async_trait]
-trait UserRepository: Send + Sync {
-    async fn find_by_id(&self, id: u64) -> Result<Option<User>, DbError>;
-    async fn save(&self, user: &User) -> Result<(), DbError>;
-}
-
-// Production implementation
-struct PostgresUserRepo {
-    pool: PgPool,
-}
-
-#[async_trait]
-impl UserRepository for PostgresUserRepo {
-    async fn find_by_id(&self, id: u64) -> Result<Option<User>, DbError> {
-        sqlx::query_as("SELECT * FROM users WHERE id = $1")
-            .bind(id)
-            .fetch_optional(&self.pool)
-            .await
-    }
-    // ...
-}
-
-// Service depends on trait, not concrete type
-struct UserService<R: UserRepository> {
-    repo: R,
-}
-
-impl<R: UserRepository> UserService<R> {
-    async fn get_user(&self, id: u64) -> Result<User, Error> {
-        self.repo.find_by_id(id).await?
-            .ok_or(Error::NotFound)
-    }
-}
-
-// Test with mock
-#[cfg(test)]
-mod tests {
-    struct MockUserRepo {
-        users: HashMap<u64, User>,
-    }
-    
-    #[async_trait]
-    impl UserRepository for MockUserRepo {
-        async fn find_by_id(&self, id: u64) -> Result<Option<User>, DbError> {
-            Ok(self.users.get(&id).cloned())
-        }
-        // ...
-    }
-    
-    #[tokio::test]
-    async fn test_get_user_found() {
-        let mut mock = MockUserRepo { users: HashMap::new() };
-        mock.users.insert(1, User { id: 1, name: "Alice".into() });
-        
-        let service = UserService { repo: mock };
-        let user = service.get_user(1).await.unwrap();
-        
-        assert_eq!(user.name, "Alice");
-    }
-    
-    #[tokio::test]
-    async fn test_get_user_not_found() {
-        let mock = MockUserRepo { users: HashMap::new() };
-        let service = UserService { repo: mock };
-        
-        let result = service.get_user(999).await;
-        assert!(matches!(result, Err(Error::NotFound)));
-    }
-}
-```
-
-## mockall Crate
-
-```rust
-use mockall::*;
-use mockall::predicate::*;
-
-#[automock]
-#[async_trait]
-trait Database: Send + Sync {
-    async fn query(&self, sql: &str) -> Result<Vec<Row>, Error>;
-}
-
-#[tokio::test]
-async fn test_with_mockall() {
-    let mut mock = MockDatabase::new();
-    
-    mock.expect_query()
-        .with(eq("SELECT 1"))
-        .times(1)
-        .returning(|_| Ok(vec![Row::new()]));
-    
-    let result = mock.query("SELECT 1").await;
-    assert!(result.is_ok());
-}
-```
-
-## Testing Error Paths
-
-```rust
-#[async_trait]
-trait HttpClient: Send + Sync {
-    async fn get(&self, url: &str) -> Result<Response, HttpError>;
-}
-
-struct FailingClient;
-
-#[async_trait]
-impl HttpClient for FailingClient {
-    async fn get(&self, _url: &str) -> Result<Response, HttpError> {
-        Err(HttpError::Timeout)  // Always fails
-    }
-}
-
-#[tokio::test]
-async fn test_handles_timeout() {
-    let client = FailingClient;
-    let service = ApiService { client };
-    
-    let result = service.fetch_data().await;
-    assert!(matches!(result, Err(Error::NetworkError(_))));
-}
-```
-
-## Dynamic Dispatch Alternative
-
-```rust
-// When you don't want generics everywhere
-struct UserService {
-    repo: Box<dyn UserRepository>,
-}
-
-impl UserService {
-    fn new(repo: impl UserRepository + 'static) -> Self {
-        Self { repo: Box::new(repo) }
-    }
-}
-
-// Slight runtime cost but cleaner API
-```
-
-## Cargo.toml
-
-```toml
-[dev-dependencies]
-mockall = "0.11"
-async-trait = "0.1"  # For async trait mocking
-```
-
-## See Also
-
-- [api-sealed-trait](./api-sealed-trait.md) - Trait design
-- [test-proptest-properties](./test-proptest-properties.md) - Property-based testing
-- [proj-lib-main-split](./proj-lib-main-split.md) - Testable architecture

package/template/agent/skills/rust-developer/references/rust-rules/test-mockall-mocking.md

@@ -1,226 +0,0 @@
-# test-mockall-mocking
-
-> Use mockall for trait mocking
-
-## Why It Matters
-
-Unit tests should isolate the code under test from external dependencies (databases, APIs, file systems). Mockall generates mock implementations of traits, allowing you to control and verify behavior without real dependencies.
-
-## Setup
-
-```toml
-# Cargo.toml
-[dev-dependencies]
-mockall = "0.12"
-```
-
-## Basic Usage
-
-```rust
-use mockall::automock;
-
-#[automock]
-trait Database {
-    fn get_user(&self, id: u64) -> Option<User>;
-    fn save_user(&self, user: &User) -> Result<(), Error>;
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use mockall::predicate::*;
-    
-    #[test]
-    fn test_get_user() {
-        let mut mock = MockDatabase::new();
-        
-        mock.expect_get_user()
-            .with(eq(42))
-            .returning(|_| Some(User { id: 42, name: "Alice".into() }));
-        
-        let service = UserService::new(mock);
-        let user = service.find_user(42);
-        
-        assert_eq!(user.unwrap().name, "Alice");
-    }
-}
-```
-
-## Expectations
-
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-    
-    #[test]
-    fn test_save_calls() {
-        let mut mock = MockDatabase::new();
-        
-        // Expect exactly one call
-        mock.expect_save_user()
-            .times(1)
-            .returning(|_| Ok(()));
-        
-        // Expect call with specific argument
-        mock.expect_get_user()
-            .with(eq(42))
-            .returning(|_| Some(User::default()));
-        
-        // Expect multiple calls
-        mock.expect_get_user()
-            .times(3..)  // At least 3 times
-            .returning(|_| None);
-        
-        // Expectations are verified on drop
-    }
-}
-```
-
-## Predicates
-
-```rust
-use mockall::predicate::*;
-
-mock.expect_process()
-    .with(eq(42))                    // Exact match
-    .returning(|_| Ok(()));
-
-mock.expect_validate()
-    .with(function(|s: &str| s.len() > 5))  // Custom predicate
-    .returning(|_| true);
-
-mock.expect_search()
-    .withf(|query, limit| {           // Multiple args
-        query.len() < 100 && *limit <= 1000
-    })
-    .returning(|_, _| vec![]);
-```
-
-## Sequences
-
-```rust
-use mockall::Sequence;
-
-#[test]
-fn test_ordered_calls() {
-    let mut seq = Sequence::new();
-    let mut mock = MockDatabase::new();
-    
-    mock.expect_connect()
-        .times(1)
-        .in_sequence(&mut seq)
-        .returning(|| Ok(()));
-    
-    mock.expect_query()
-        .times(1)
-        .in_sequence(&mut seq)
-        .returning(|_| Ok(vec![]));
-    
-    mock.expect_disconnect()
-        .times(1)
-        .in_sequence(&mut seq)
-        .returning(|| Ok(()));
-}
-```
-
-## Return Values
-
-```rust
-// Fixed value
-mock.expect_count().returning(|| 42);
-
-// Based on input
-mock.expect_double().returning(|x| x * 2);
-
-// Different values per call
-mock.expect_next()
-    .times(3)
-    .returning(|| 1)
-    .returning(|| 2)
-    .returning(|| 3);
-
-// Return owned values
-mock.expect_get_name()
-    .returning(|| "Alice".to_string());
-```
-
-## Mocking External Traits
-
-```rust
-// For traits you don't own
-#[cfg_attr(test, mockall::automock)]
-trait HttpClient {
-    fn get(&self, url: &str) -> Result<Response, Error>;
-}
-
-// In production
-struct RealHttpClient;
-impl HttpClient for RealHttpClient {
-    fn get(&self, url: &str) -> Result<Response, Error> { /* ... */ }
-}
-
-// In tests
-#[cfg(test)]
-fn mock_client() -> MockHttpClient {
-    let mut mock = MockHttpClient::new();
-    mock.expect_get()
-        .returning(|_| Ok(Response::new(200, "OK")));
-    mock
-}
-```
-
-## Async Mocking
-
-```rust
-#[automock]
-#[async_trait]
-trait AsyncDatabase {
-    async fn fetch(&self, id: u64) -> Option<Data>;
-}
-
-#[tokio::test]
-async fn test_async() {
-    let mut mock = MockAsyncDatabase::new();
-    
-    mock.expect_fetch()
-        .returning(|_| Some(Data::default()));
-    
-    let result = mock.fetch(1).await;
-    assert!(result.is_some());
-}
-```
-
-## Design for Testability
-
-```rust
-// Accept trait, not concrete type
-struct Service<D: Database> {
-    db: D,
-}
-
-impl<D: Database> Service<D> {
-    fn new(db: D) -> Self {
-        Self { db }
-    }
-}
-
-// Tests use mock
-#[test]
-fn test_service() {
-    let mock = MockDatabase::new();
-    let service = Service::new(mock);
-}
-
-// Production uses real implementation
-fn main() {
-    let db = PostgresDatabase::connect();
-    let service = Service::new(db);
-}
-```
-
-## See Also
-
-- [test-mock-traits](./test-mock-traits.md) - Mock trait design
-- [test-proptest-properties](./test-proptest-properties.md) - Property testing
-- [test-arrange-act-assert](./test-arrange-act-assert.md) - Test structure

package/template/agent/skills/rust-developer/references/rust-rules/test-proptest-properties.md

@@ -1,161 +0,0 @@
-# test-proptest-properties
-
-> Use proptest for property-based testing
-
-## Why It Matters
-
-Property-based testing generates random inputs to verify that properties hold across all possible values, not just hand-picked examples. Proptest finds edge cases you wouldn't think to test manually—empty strings, integer overflows, unicode edge cases.
-
-## Setup
-
-```toml
-# Cargo.toml
-[dev-dependencies]
-proptest = "1.0"
-```
-
-## Basic Usage
-
-```rust
-use proptest::prelude::*;
-
-proptest! {
-    #[test]
-    fn test_reverse_reverse_is_identity(s in ".*") {
-        let reversed: String = s.chars().rev().collect();
-        let double_reversed: String = reversed.chars().rev().collect();
-        assert_eq!(s, double_reversed);
-    }
-    
-    #[test]
-    fn test_sort_is_idempotent(mut v in prop::collection::vec(any::<i32>(), 0..100)) {
-        v.sort();
-        let sorted = v.clone();
-        v.sort();
-        assert_eq!(v, sorted);
-    }
-}
-```
-
-## Common Strategies
-
-```rust
-use proptest::prelude::*;
-
-proptest! {
-    // Any type implementing Arbitrary
-    #[test]
-    fn test_i32(x in any::<i32>()) { }
-    
-    // Regex-based string generation
-    #[test]
-    fn test_email(email in "[a-z]+@[a-z]+\\.[a-z]{2,3}") { }
-    
-    // Ranges
-    #[test]
-    fn test_range(x in 0..100i32) { }
-    
-    // Collections
-    #[test]
-    fn test_vec(v in prop::collection::vec(any::<i32>(), 0..10)) { }
-    
-    // Optionals
-    #[test]
-    fn test_option(opt in prop::option::of(any::<i32>())) { }
-}
-```
-
-## Custom Strategies
-
-```rust
-use proptest::prelude::*;
-
-#[derive(Debug, Clone)]
-struct User {
-    name: String,
-    age: u8,
-}
-
-fn user_strategy() -> impl Strategy<Value = User> {
-    ("[a-zA-Z]{1,20}", 0..120u8)
-        .prop_map(|(name, age)| User { name, age })
-}
-
-proptest! {
-    #[test]
-    fn test_user(user in user_strategy()) {
-        assert!(user.age < 150);
-        assert!(!user.name.is_empty());
-    }
-}
-
-// Or derive Arbitrary
-use proptest_derive::Arbitrary;
-
-#[derive(Debug, Arbitrary)]
-struct Point {
-    x: i32,
-    y: i32,
-}
-```
-
-## Properties to Test
-
-| Property | Example |
-|----------|---------|
-| Roundtrip | `decode(encode(x)) == x` |
-| Idempotence | `f(f(x)) == f(x)` |
-| Commutativity | `f(a, b) == f(b, a)` |
-| Associativity | `f(f(a, b), c) == f(a, f(b, c))` |
-| Identity | `f(x, identity) == x` |
-| Invariants | `len(push(v, x)) == len(v) + 1` |
-
-## Example: Parser Roundtrip
-
-```rust
-proptest! {
-    #[test]
-    fn parse_roundtrip(config in valid_config_strategy()) {
-        let serialized = config.to_string();
-        let parsed = Config::parse(&serialized).unwrap();
-        assert_eq!(config, parsed);
-    }
-}
-```
-
-## Shrinking
-
-Proptest automatically shrinks failing inputs to minimal cases:
-
-```rust
-// If this fails with vec![100, 50, 75, 25, 0]
-// Proptest will shrink to vec![1, 0] (minimal failing case)
-proptest! {
-    #[test]
-    fn test_sorted(v in prop::collection::vec(0..1000i32, 1..100)) {
-        let sorted = is_sorted(&v);
-        // This will fail and shrink
-    }
-}
-```
-
-## Configuration
-
-```rust
-proptest! {
-    #![proptest_config(ProptestConfig {
-        cases: 1000,  // More test cases
-        max_shrink_iters: 10000,  // More shrinking
-        ..ProptestConfig::default()
-    })]
-    
-    #[test]
-    fn extensive_test(x in any::<i32>()) { }
-}
-```
-
-## See Also
-
-- [test-criterion-bench](./test-criterion-bench.md) - Benchmarking
-- [test-mockall-mocking](./test-mockall-mocking.md) - Mocking
-- [test-arrange-act-assert](./test-arrange-act-assert.md) - Test structure

package/template/agent/skills/rust-developer/references/rust-rules/test-should-panic.md

@@ -1,130 +0,0 @@
-# test-should-panic
-
-> Use `#[should_panic]` to test that code panics as expected
-
-## Why It Matters
-
-Some code should panic on invalid inputs or invariant violations. `#[should_panic]` verifies the panic occurs, optionally checking the panic message. This ensures defensive panics work correctly and documents expected panic conditions.
-
-## Bad
-
-```rust
-#[test]
-fn test_panic() {
-    // Just calling panicking code makes test fail
-    divide(1, 0);  // Test fails with panic
-}
-
-// Using catch_unwind is verbose
-#[test]
-fn test_panic_manual() {
-    let result = std::panic::catch_unwind(|| divide(1, 0));
-    assert!(result.is_err());
-}
-```
-
-## Good
-
-```rust
-#[test]
-#[should_panic]
-fn divide_by_zero_panics() {
-    divide(1, 0);  // Test passes when this panics
-}
-
-// With expected message
-#[test]
-#[should_panic(expected = "division by zero")]
-fn divide_by_zero_panics_with_message() {
-    divide(1, 0);  // Panics with "division by zero"
-}
-
-// Partial message match
-#[test]
-#[should_panic(expected = "index out of bounds")]
-fn index_panic_contains_message() {
-    let v = vec![1, 2, 3];
-    let _ = v[100];  // Message contains "index out of bounds"
-}
-```
-
-## Testing Invariants
-
-```rust
-struct NonEmpty<T>(Vec<T>);
-
-impl<T> NonEmpty<T> {
-    fn new(items: Vec<T>) -> Self {
-        assert!(!items.is_empty(), "NonEmpty cannot be empty");
-        NonEmpty(items)
-    }
-}
-
-#[test]
-#[should_panic(expected = "NonEmpty cannot be empty")]
-fn non_empty_rejects_empty_vec() {
-    NonEmpty::new(Vec::<i32>::new());
-}
-
-#[test]
-fn non_empty_accepts_non_empty_vec() {
-    let ne = NonEmpty::new(vec![1, 2, 3]);
-    assert_eq!(ne.0.len(), 3);
-}
-```
-
-## With expect() Messages
-
-```rust
-fn get_config_value(key: &str) -> String {
-    CONFIG.get(key)
-        .expect(&format!("missing required config: {}", key))
-        .to_string()
-}
-
-#[test]
-#[should_panic(expected = "missing required config: DATABASE_URL")]
-fn missing_config_panics_with_key() {
-    get_config_value("DATABASE_URL");
-}
-```
-
-## When NOT to Use should_panic
-
-```rust
-// ❌ For recoverable errors - use Result
-#[test]
-#[should_panic]  // Wrong: this should return Err, not panic
-fn invalid_input_panics() {
-    parse_config("invalid");  // Should return Err, not panic
-}
-
-// ✅ Return Result and test the error
-#[test]
-fn invalid_input_returns_error() {
-    let result = parse_config("invalid");
-    assert!(result.is_err());
-}
-```
-
-## Combining with Result
-
-```rust
-#[test]
-#[should_panic]
-fn test_panics() -> Result<(), Error> {
-    // Can combine with Result for setup
-    let data = setup_test_data()?;
-    
-    // This should panic
-    process_invalid(&data);
-    
-    Ok(())  // Never reached
-}
-```
-
-## See Also
-
-- [err-result-over-panic](./err-result-over-panic.md) - Panic vs Result
-- [err-expect-bugs-only](./err-expect-bugs-only.md) - When to use expect
-- [test-descriptive-names](./test-descriptive-names.md) - Test naming