agy-superpowers 5.1.3 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/test-integration-dir.md

@@ -0,0 +1,144 @@
+# test-integration-dir
+
+> Put integration tests in the `tests/` directory
+
+## Why It Matters
+
+Integration tests live in `tests/` at the crate root, separate from `src/`. Each file in `tests/` is compiled as a separate crate, testing your library's public API as external users would. This separation ensures you're testing the real public interface, not implementation details.
+
+## Structure
+
+```
+my_project/
+├── Cargo.toml
+├── src/
+│   ├── lib.rs
+│   └── internal.rs
+└── tests/
+    ├── integration_test.rs    # Each file is a separate test binary
+    ├── api_tests.rs
+    └── common/                 # Shared test utilities
+        └── mod.rs
+```
+
+## Bad
+
+```rust
+// src/lib.rs
+// Mixing integration test logic in library code
+#[test]
+fn integration_test_full_workflow() {
+    // This is a unit test location, not integration
+}
+```
+
+## Good
+
+```rust
+// tests/integration_test.rs
+use my_crate::{Client, Config};  // Uses public API only
+
+#[test]
+fn test_full_workflow() {
+    let config = Config::default();
+    let client = Client::new(config);
+    
+    let result = client.process("input");
+    assert!(result.is_ok());
+}
+
+#[test]
+fn test_error_handling() {
+    let client = Client::new(Config::strict());
+    
+    let result = client.process("invalid");
+    assert!(matches!(result, Err(Error::InvalidInput { .. })));
+}
+```
+
+## Shared Test Utilities
+
+```rust
+// tests/common/mod.rs
+use my_crate::Config;
+
+pub fn test_config() -> Config {
+    Config {
+        timeout: Duration::from_secs(5),
+        retries: 3,
+        debug: true,
+    }
+}
+
+pub fn setup_test_environment() {
+    // Set up test fixtures
+}
+
+// tests/api_tests.rs
+mod common;
+
+use my_crate::Client;
+
+#[test]
+fn test_with_shared_config() {
+    common::setup_test_environment();
+    let client = Client::new(common::test_config());
+    // ...
+}
+```
+
+## Organizing Many Tests
+
+```rust
+// tests/api/mod.rs
+mod auth;
+mod users;
+mod orders;
+
+// tests/api/auth.rs
+use my_crate::auth::{login, logout};
+
+#[test]
+fn test_login_success() { ... }
+
+#[test]
+fn test_login_invalid_credentials() { ... }
+
+// tests/api/users.rs
+use my_crate::users::{create_user, get_user};
+
+#[test]
+fn test_create_user() { ... }
+```
+
+## Integration vs Unit Tests
+
+| Unit Tests | Integration Tests |
+|------------|-------------------|
+| In `src/` with `#[cfg(test)]` | In `tests/` directory |
+| Access private items | Public API only |
+| Test individual functions | Test module interactions |
+| Fast, isolated | May be slower |
+| `cargo test --lib` | `cargo test --test '*'` |
+
+## Running Specific Tests
+
+```bash
+# Run all tests
+cargo test
+
+# Run only integration tests
+cargo test --test '*'
+
+# Run specific integration test file
+cargo test --test integration_test
+
+# Run tests matching pattern
+cargo test --test api_tests test_login
+```
+
+## See Also
+
+- [test-cfg-test-module](./test-cfg-test-module.md) - Unit test modules
+- [test-descriptive-names](./test-descriptive-names.md) - Test naming
+- [test-tokio-async](./test-tokio-async.md) - Async integration tests

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

@@ -0,0 +1,189 @@
+# 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

@@ -0,0 +1,226 @@
+# 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

@@ -0,0 +1,161 @@
+# 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