agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/test-descriptive-names.md

@@ -0,0 +1,142 @@
+# test-descriptive-names
+
+> Use descriptive test names that explain what is being tested
+
+## Why It Matters
+
+Test names appear in test output and serve as documentation. A good test name tells you what behavior is being verified without reading the test body. When a test fails, a descriptive name immediately tells you what broke.
+
+## Bad
+
+```rust
+#[test]
+fn test1() { ... }
+
+#[test]
+fn test_parse() { ... }  // Parse what? What behavior?
+
+#[test]
+fn it_works() { ... }
+
+#[test]
+fn test_function() { ... }
+
+// Failure output: "test test_parse ... FAILED"
+// What failed? No idea.
+```
+
+## Good
+
+```rust
+#[test]
+fn parse_returns_error_for_empty_input() { ... }
+
+#[test]
+fn parse_handles_unicode_characters() { ... }
+
+#[test]
+fn user_creation_requires_valid_email() { ... }
+
+#[test]
+fn expired_token_is_rejected() { ... }
+
+// Failure output: "test parse_returns_error_for_empty_input ... FAILED"
+// Immediately know what broke!
+```
+
+## Naming Patterns
+
+```rust
+// Pattern: function_condition_expected_result
+#[test]
+fn parse_valid_json_returns_document() { ... }
+
+#[test]
+fn parse_invalid_json_returns_syntax_error() { ... }
+
+// Pattern: scenario_expectation
+#[test]
+fn empty_cart_has_zero_total() { ... }
+
+#[test]
+fn adding_item_increases_cart_total() { ... }
+
+// Pattern: when_given_then (BDD-style)
+#[test]
+fn when_user_not_found_then_returns_404() { ... }
+```
+
+## Edge Cases
+
+```rust
+#[test]
+fn handles_empty_string() { ... }
+
+#[test]
+fn handles_max_length_input() { ... }
+
+#[test]
+fn handles_unicode_emoji() { ... }
+
+#[test]
+fn handles_null_bytes() { ... }
+
+#[test]
+fn handles_concurrent_access() { ... }
+```
+
+## Error Cases
+
+```rust
+#[test]
+fn rejects_negative_quantity() { ... }
+
+#[test]
+fn returns_error_for_invalid_email_format() { ... }
+
+#[test]
+fn panics_on_double_initialization() { ... }
+
+#[test]
+fn timeout_returns_timeout_error() { ... }
+```
+
+## Module Organization
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    mod parsing {
+        use super::*;
+        
+        #[test]
+        fn accepts_valid_json() { ... }
+        
+        #[test]
+        fn rejects_trailing_comma() { ... }
+    }
+    
+    mod validation {
+        use super::*;
+        
+        #[test]
+        fn requires_name_field() { ... }
+        
+        #[test]
+        fn email_must_contain_at_symbol() { ... }
+    }
+}
+
+// Test output:
+// tests::parsing::accepts_valid_json
+// tests::parsing::rejects_trailing_comma
+// tests::validation::requires_name_field
+```
+
+## See Also
+
+- [test-arrange-act-assert](./test-arrange-act-assert.md) - Test structure
+- [test-cfg-test-module](./test-cfg-test-module.md) - Test module organization
+- [doc-examples-section](./doc-examples-section.md) - Documentation tests

package/template/agent/skills/rust-developer/references/rust-rules/test-doctest-examples.md

@@ -0,0 +1,168 @@
+# test-doctest-examples
+
+> Keep documentation examples as executable doctests
+
+## Why It Matters
+
+Doctests are examples in documentation that are automatically tested. They serve dual purposes: demonstrating usage to readers and verifying the examples compile and work. When your API changes, failing doctests catch outdated documentation.
+
+## Bad
+
+```rust
+/// Parses a number from a string.
+/// 
+/// Example:
+/// let n = parse("42");  // Not tested!
+/// assert_eq!(n, 42);
+pub fn parse(s: &str) -> i32 {
+    s.parse().unwrap()
+}
+
+// Documentation can become outdated:
+/// Adds two numbers.
+/// 
+/// ```
+/// let sum = add(1, 2, 3);  // Wrong number of args - not caught!
+/// ```
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+```
+
+## Good
+
+```rust
+/// Parses a number from a string.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use my_crate::parse;
+/// 
+/// let n = parse("42");
+/// assert_eq!(n, 42);
+/// ```
+pub fn parse(s: &str) -> i32 {
+    s.parse().unwrap()
+}
+
+/// Adds two numbers.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use my_crate::add;
+/// 
+/// let sum = add(1, 2);
+/// assert_eq!(sum, 3);
+/// ```
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+```
+
+## Hiding Setup Code
+
+```rust
+/// Processes data from a file.
+/// 
+/// # Examples
+/// 
+/// ```
+/// # use std::io::Write;
+/// # let mut file = tempfile::NamedTempFile::new().unwrap();
+/// # writeln!(file, "test data").unwrap();
+/// # let path = file.path();
+/// use my_crate::process_file;
+/// 
+/// let result = process_file(path)?;
+/// assert!(!result.is_empty());
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+pub fn process_file(path: &Path) -> Result<String, Error> {
+    std::fs::read_to_string(path).map_err(Error::from)
+}
+```
+
+## Showing Error Handling
+
+```rust
+/// Parses and validates an email address.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use my_crate::Email;
+/// 
+/// let email = Email::parse("user@example.com")?;
+/// assert_eq!(email.domain(), "example.com");
+/// # Ok::<(), my_crate::EmailError>(())
+/// ```
+/// 
+/// # Errors
+/// 
+/// Returns error for invalid format:
+/// 
+/// ```
+/// use my_crate::Email;
+/// 
+/// assert!(Email::parse("not-an-email").is_err());
+/// ```
+pub fn parse(s: &str) -> Result<Email, EmailError> {
+    // ...
+}
+```
+
+## no_run and ignore
+
+```rust
+/// Starts the server.
+/// 
+/// ```no_run
+/// use my_crate::Server;
+/// 
+/// // This compiles but doesn't run (would block forever)
+/// Server::new().run();
+/// ```
+pub fn run(&self) { ... }
+
+/// Platform-specific example.
+/// 
+/// ```ignore
+/// // This might not compile on all platforms
+/// use windows_specific::Feature;
+/// ```
+```
+
+## compile_fail
+
+```rust
+/// This type is not Clone.
+/// 
+/// ```compile_fail
+/// use my_crate::UniqueHandle;
+/// 
+/// let a = UniqueHandle::new();
+/// let b = a.clone();  // Error: Clone not implemented
+/// ```
+pub struct UniqueHandle { ... }
+```
+
+## Running Doctests
+
+```bash
+# Run all tests including doctests
+cargo test
+
+# Run only doctests
+cargo test --doc
+
+# Run doctests for specific item
+cargo test --doc my_function
+```
+
+## See Also
+
+- [doc-examples-section](./doc-examples-section.md) - Documentation structure
+- [doc-hidden-setup](./doc-hidden-setup.md) - Hiding setup code
+- [doc-question-mark](./doc-question-mark.md) - Error handling in examples

package/template/agent/skills/rust-developer/references/rust-rules/test-fixture-raii.md

@@ -0,0 +1,151 @@
+# test-fixture-raii
+
+> Use RAII pattern (Drop trait) for automatic test cleanup
+
+## Why It Matters
+
+Tests often need setup and teardown—creating temp files, starting servers, setting environment variables. Using RAII (Resource Acquisition Is Initialization) with Drop ensures cleanup happens automatically, even if the test panics. This prevents test pollution and resource leaks.
+
+## Bad
+
+```rust
+#[test]
+fn test_with_temp_file() {
+    let path = "/tmp/test_file.txt";
+    std::fs::write(path, "test data").unwrap();
+    
+    let result = process_file(path);
+    
+    std::fs::remove_file(path).unwrap();  // Might not run if test panics!
+    assert!(result.is_ok());
+}
+
+#[test]
+fn test_with_env_var() {
+    std::env::set_var("MY_VAR", "test_value");
+    
+    let result = read_config();
+    
+    std::env::remove_var("MY_VAR");  // Might not run if test panics!
+    assert!(result.is_ok());
+}
+```
+
+## Good
+
+```rust
+use tempfile::NamedTempFile;
+
+#[test]
+fn test_with_temp_file() {
+    // Arrange - file deleted automatically when `file` drops
+    let file = NamedTempFile::new().unwrap();
+    std::fs::write(file.path(), "test data").unwrap();
+    
+    // Act
+    let result = process_file(file.path());
+    
+    // Assert - file cleaned up even if assertion panics
+    assert!(result.is_ok());
+}
+
+// Custom RAII guard for environment variables
+struct EnvGuard {
+    key: String,
+    original: Option<String>,
+}
+
+impl EnvGuard {
+    fn set(key: &str, value: &str) -> Self {
+        let original = std::env::var(key).ok();
+        std::env::set_var(key, value);
+        EnvGuard {
+            key: key.to_string(),
+            original,
+        }
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        match &self.original {
+            Some(v) => std::env::set_var(&self.key, v),
+            None => std::env::remove_var(&self.key),
+        }
+    }
+}
+
+#[test]
+fn test_with_env_var() {
+    let _guard = EnvGuard::set("MY_VAR", "test_value");
+    
+    let result = read_config();
+    
+    assert!(result.is_ok());
+}  // MY_VAR automatically restored
+```
+
+## Common RAII Patterns
+
+```rust
+// Temporary directory
+use tempfile::TempDir;
+
+#[test]
+fn test_with_temp_dir() {
+    let dir = TempDir::new().unwrap();
+    let file_path = dir.path().join("test.txt");
+    std::fs::write(&file_path, "data").unwrap();
+    
+    // dir and all contents deleted on drop
+}
+
+// Server guard
+struct TestServer {
+    handle: std::thread::JoinHandle<()>,
+    shutdown: std::sync::mpsc::Sender<()>,
+}
+
+impl Drop for TestServer {
+    fn drop(&mut self) {
+        let _ = self.shutdown.send(());
+        // Wait for server to stop
+    }
+}
+
+// Database transaction rollback
+struct TestTransaction<'a> {
+    conn: &'a mut Connection,
+}
+
+impl Drop for TestTransaction<'_> {
+    fn drop(&mut self) {
+        self.conn.execute("ROLLBACK").unwrap();
+    }
+}
+```
+
+## scopeguard Crate
+
+```rust
+use scopeguard::defer;
+
+#[test]
+fn test_with_defer() {
+    let path = "/tmp/test_file.txt";
+    std::fs::write(path, "data").unwrap();
+    
+    defer! {
+        std::fs::remove_file(path).ok();
+    }
+    
+    // Test logic here
+    // File removed when scope exits
+}
+```
+
+## See Also
+
+- [test-arrange-act-assert](./test-arrange-act-assert.md) - Test structure
+- [test-tokio-async](./test-tokio-async.md) - Async test cleanup
+- [test-mock-traits](./test-mock-traits.md) - Mocking with RAII

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