@grimoire-cc/cli 0.13.3 → 0.14.0

package/packs/rust-pack/skills/grimoire.unit-testing-rust/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: grimoire.unit-testing-rust
+description: "Rust unit testing specialist. Patterns and best practices for the built-in test framework, mockall, and proptest. Use when writing tests for .rs files, or asking about Rust testing patterns, test modules, mocking traits, property-based testing, integration tests."
+---
+
+# Rust Unit Testing
+
+Focused guidance for writing clean, idiomatic unit tests in Rust projects.
+
+## Framework Selection
+
+### Detection
+
+1. Check existing test files first — always match what the project uses
+2. Check `Cargo.toml` for `mockall`, `proptest`, `rstest` in `[dev-dependencies]`
+3. Check existing `#[cfg(test)] mod tests` blocks for assertion style
+
+### Decision Table
+
+| Condition | Use | Reason |
+|-----------|-----|--------|
+| Project has existing tests | **Match existing** | Consistency is paramount |
+| Any Rust project | **Built-in `#[test]`** | Always available, zero deps |
+| Need trait mocking | **mockall** | Derive macros for mock generation |
+| Need parameterized tests | **rstest** | `#[rstest]` with fixtures and cases |
+| Need property-based | **proptest** | QuickCheck-style property testing |
+| User explicitly requests | **Requested** | Respect user preference |
+
+## Naming Conventions
+
+Use `test_method_scenario_expected` with snake_case:
+
+```rust
+// Pattern: test_method_scenario_expected
+fn test_get_user_with_invalid_id_returns_not_found() { ... }
+fn test_calculate_total_with_discount_applies_percentage() { ... }
+fn test_parse_config_with_missing_fields_returns_error() { ... }
+```
+
+## Patterns
+
+### AAA with built-in tests
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn process_order_with_valid_order_returns_id() {
+        // Arrange
+        let mut mock_repo = MockOrderRepository::new();
+        mock_repo.expect_save()
+            .returning(|_| Ok(Order { id: "123".into() }));
+        let service = OrderService::new(Box::new(mock_repo));
+
+        // Act
+        let result = service.process_order(&valid_order());
+
+        // Assert
+        assert_eq!(result.unwrap().id, "123");
+    }
+
+    #[test]
+    fn process_order_with_invalid_order_returns_error() {
+        // Arrange
+        let service = OrderService::new(Box::new(MockOrderRepository::new()));
+
+        // Act
+        let result = service.process_order(&invalid_order());
+
+        // Assert
+        assert!(matches!(result, Err(ServiceError::Validation(_))));
+    }
+}
+```
+
+### Parameterized with rstest
+
+```rust
+use rstest::rstest;
+
+#[rstest]
+#[case(0, 100.0)]
+#[case(10, 90.0)]
+#[case(50, 50.0)]
+fn apply_discount_calculates_correctly(#[case] discount: u32, #[case] expected: f64) {
+    assert_eq!(apply_discount(100.0, discount), expected);
+}
+```
+
+### rstest Fixtures
+
+```rust
+use rstest::*;
+
+#[fixture]
+fn service() -> OrderService {
+    let repo = InMemoryOrderRepository::new();
+    OrderService::new(Box::new(repo))
+}
+
+#[rstest]
+fn process_order_with_valid_order_succeeds(service: OrderService) {
+    let result = service.process_order(&valid_order());
+    assert!(result.is_ok());
+}
+```
+
+### Error Testing
+
+```rust
+// Check Result is Err
+#[test]
+fn divide_by_zero_returns_error() {
+    let result = divide(1, 0);
+    assert!(result.is_err());
+}
+
+// Match specific error variant
+#[test]
+fn parse_invalid_input_returns_parse_error() {
+    let result = parse("bad input");
+    assert!(matches!(result, Err(ParseError::InvalidFormat(_))));
+}
+
+// Check error message
+#[test]
+fn validate_empty_name_returns_error_message() {
+    let err = validate(User { name: "".into() }).unwrap_err();
+    assert_eq!(err.to_string(), "name cannot be empty");
+}
+
+// Should panic
+#[test]
+#[should_panic(expected = "index out of bounds")]
+fn access_out_of_bounds_panics() {
+    let v = vec![1, 2, 3];
+    let _ = v[10];
+}
+```
+
+### Async Testing (tokio)
+
+```rust
+#[tokio::test]
+async fn fetch_user_returns_data() {
+    // Arrange
+    let client = MockHttpClient::new();
+    client.expect_get().returning(|_| Ok(user_response()));
+
+    // Act
+    let user = fetch_user(&client, "123").await.unwrap();
+
+    // Assert
+    assert_eq!(user.name, "Alice");
+}
+```
+
+## Mocking
+
+### mockall
+
+```rust
+use mockall::*;
+use mockall::predicate::*;
+
+#[automock]
+trait OrderRepository {
+    fn save(&self, order: &Order) -> Result<Order, RepositoryError>;
+    fn find_by_id(&self, id: &str) -> Result<Option<Order>, RepositoryError>;
+}
+
+// Usage in tests
+let mut mock = MockOrderRepository::new();
+mock.expect_save()
+    .with(predicate::always())
+    .times(1)
+    .returning(|order| Ok(Order { id: "123".into(), ..order.clone() }));
+mock.expect_find_by_id()
+    .with(eq("123"))
+    .returning(|_| Ok(Some(Order { id: "123".into(), ..Default::default() })));
+```
+
+### Manual fakes (for simple cases)
+
+```rust
+// Test-only implementation
+struct FakeOrderRepository {
+    orders: Vec<Order>,
+}
+
+impl OrderRepository for FakeOrderRepository {
+    fn save(&self, order: &Order) -> Result<Order, RepositoryError> {
+        Ok(Order { id: "fake-id".into(), ..order.clone() })
+    }
+    fn find_by_id(&self, id: &str) -> Result<Option<Order>, RepositoryError> {
+        Ok(self.orders.iter().find(|o| o.id == id).cloned())
+    }
+}
+```
+
+### What NOT to mock
+
+- Structs used as data containers
+- Pure functions with no side effects
+- The module under test itself
+- Standard library types
+
+Mock only at system boundaries: external APIs, databases, file system, time.
+
+## File Conventions
+
+- Unit tests: `#[cfg(test)] mod tests` at bottom of source file
+- Integration tests: `tests/` directory (each file is a separate crate)
+- Test fixtures: `tests/fixtures/` or inline
+- Run: `cargo test` (all), `cargo test -- test_name` (specific)
+- Run with output: `cargo test -- --nocapture`
+
+## Package Setup
+
+```toml
+# Cargo.toml
+[dev-dependencies]
+mockall = "0.13"       # trait mocking
+rstest = "0.22"        # parameterized tests, fixtures
+proptest = "1.5"       # property-based testing
+tokio = { version = "1", features = ["test-util", "macros", "rt"] }  # async tests
+```
+
+## Authoritative Sources
+
+- The Rust Book — Testing: https://doc.rust-lang.org/book/ch11-00-testing.html
+- mockall: https://docs.rs/mockall
+- rstest: https://docs.rs/rstest
+- proptest: https://proptest-rs.github.io/proptest
+- Kent Beck — Canon TDD: https://tidyfirst.substack.com/p/canon-tdd
+- Martin Fowler — Mocks Aren't Stubs: https://martinfowler.com/articles/mocksArentStubs.html
+
+## Reference Materials
+
+- **[Anti-Patterns](reference/anti-patterns.md)** — Common testing mistakes and how to fix them
+- **[TDD Workflow Patterns](reference/tdd-workflow-patterns.md)** — Red-Green-Refactor, Transformation Priority Premise, when to use TDD

package/packs/rust-pack/skills/grimoire.unit-testing-rust/reference/anti-patterns.md

@@ -0,0 +1,244 @@
+# Testing Anti-Patterns
+
+Common testing mistakes that reduce test value and increase maintenance cost. These are language-agnostic — they apply to any test framework.
+
+## Table of Contents
+
+- [The Liar](#the-liar)
+- [The Giant](#the-giant)
+- [Excessive Setup](#excessive-setup)
+- [The Slow Poke](#the-slow-poke)
+- [The Peeping Tom](#the-peeping-tom)
+- [The Mockery](#the-mockery)
+- [The Inspector](#the-inspector)
+- [The Flaky Test](#the-flaky-test)
+- [The Cargo Culter](#the-cargo-culter)
+- [The Hard Test](#the-hard-test)
+
+## The Liar
+
+**What it is:** A test that passes but doesn't actually verify the behavior it claims to test. It gives false confidence.
+
+**How to spot it:**
+- Test name says "validates input" but assertions only check the return type
+- Assertions are too loose (`assert result is not None` instead of checking the actual value)
+- Test catches exceptions broadly and passes regardless
+
+**Fix:** Ensure assertions directly verify the specific behavior described in the test name. Every assertion should fail if the behavior breaks.
+
+```python
+# Bad — passes even if discount logic is completely wrong
+def test_apply_discount():
+    result = apply_discount(100, 10)
+    assert result is not None
+
+# Good — fails if the calculation is wrong
+def test_apply_discount_with_10_percent_returns_90():
+    result = apply_discount(100, 10)
+    assert result == 90.0
+```
+
+## The Giant
+
+**What it is:** A single test that verifies too many things. When it fails, you can't tell which behavior broke.
+
+**How to spot it:**
+- Test has more than 8-10 assertions
+- Test name uses "and" (e.g., "creates user and sends email and updates cache")
+- Multiple Act phases in one test
+
+**Fix:** Split into focused tests, each verifying one logical concept. Multiple assertions are fine if they verify aspects of the same behavior.
+
+```typescript
+// Bad — three unrelated behaviors in one test
+test('user registration works', () => {
+  const user = register({ name: 'Alice', email: 'alice@test.com' });
+  expect(user.id).toBeDefined();
+  expect(emailService.send).toHaveBeenCalled();
+  expect(cache.set).toHaveBeenCalledWith(`user:${user.id}`, user);
+  expect(auditLog.entries).toHaveLength(1);
+});
+
+// Good — separate tests for each behavior
+test('register with valid data creates user with id', () => { ... });
+test('register with valid data sends welcome email', () => { ... });
+test('register with valid data caches the user', () => { ... });
+test('register with valid data writes audit log entry', () => { ... });
+```
+
+## Excessive Setup
+
+**What it is:** Tests that require dozens of lines of setup before the actual test logic. Often signals that the code under test has too many dependencies.
+
+**How to spot it:**
+- Arrange section is 20+ lines
+- Multiple mocks configured with complex behaviors
+- Shared setup methods that configure things most tests don't need
+
+**Fix:** Use factory methods/builders for test data. Consider whether the code under test needs refactoring to reduce dependencies. Only set up what the specific test needs.
+
+```go
+// Bad — every test sets up the entire world
+func TestProcessOrder(t *testing.T) {
+    db := setupDatabase()
+    cache := setupCache()
+    logger := setupLogger()
+    emailClient := setupEmailClient()
+    validator := NewValidator(db)
+    processor := NewProcessor(cache)
+    service := NewOrderService(db, cache, logger, emailClient, validator, processor)
+    // ... 10 more lines of setup
+    result, err := service.ProcessOrder(ctx, order)
+    assert.NoError(t, err)
+}
+
+// Good — factory method hides irrelevant details
+func TestProcessOrder_WithValidOrder_Succeeds(t *testing.T) {
+    service := newTestOrderService(t)
+    result, err := service.ProcessOrder(ctx, validOrder())
+    assert.NoError(t, err)
+    assert.Equal(t, "processed", result.Status)
+}
+```
+
+## The Slow Poke
+
+**What it is:** Tests that are slow because they use real I/O, network calls, or sleeps. Slow tests get run less frequently and slow down the feedback loop.
+
+**How to spot it:**
+- `time.Sleep()`, `Thread.sleep()`, `setTimeout` in tests
+- Real HTTP calls, database connections, file system operations
+- Test suite takes more than a few seconds for unit tests
+
+**Fix:** Mock external dependencies. Use fake implementations for I/O. Replace time-based waits with event-based synchronization.
+
+## The Peeping Tom
+
+**What it is:** Tests that access private/internal state to verify behavior instead of testing through the public interface.
+
+**How to spot it:**
+- Reflection to access private fields
+- Testing internal method calls instead of observable results
+- Assertions on implementation details (internal data structures, private counters)
+
+**Fix:** Test through the public API. If you can't verify behavior through the public interface, the class may need a design change (e.g., expose a query method or extract a collaborator).
+
+## The Mockery
+
+**What it is:** Tests that mock so heavily that they're testing mock configurations rather than real behavior. Every dependency is mocked, including simple value objects.
+
+**How to spot it:**
+- More mock setup lines than actual test logic
+- Mocking concrete classes, value objects, or data structures
+- Test passes but the real system fails because mocks don't match reality
+
+**Fix:** Only mock at system boundaries (external services, databases, clocks). Use real implementations for in-process collaborators when practical.
+
+## The Inspector
+
+**What it is:** Tests that verify exact method calls and their order rather than outcomes. They break whenever the implementation changes, even if behavior is preserved.
+
+**How to spot it:**
+- `verify(mock, times(1)).method()` for every mock interaction
+- Assertions on call order
+- Test breaks when you refactor without changing behavior
+
+**Fix:** Verify state (the result) rather than interactions (how it got there). Only verify interactions for side effects that ARE the behavior (e.g., "email was sent").
+
+```java
+// Bad — breaks if implementation changes sort algorithm
+verify(sorter, times(1)).quickSort(any());
+verify(sorter, never()).mergeSort(any());
+
+// Good — verifies the outcome
+assertThat(result).isSortedAccordingTo(naturalOrder());
+```
+
+## The Flaky Test
+
+**What it is:** Tests that pass and fail intermittently without code changes. They erode trust in the test suite.
+
+**Common causes:**
+- Time-dependent logic (`new Date()`, `time.Now()`)
+- Random data without fixed seeds
+- Shared mutable state between tests
+- Race conditions in async tests
+- Dependency on test execution order
+
+**Fix:** Inject time as a dependency. Use fixed seeds for randomness. Ensure test isolation. Use proper async synchronization.
+
+## The Cargo Culter
+
+**What it is:** Writing tests to hit a coverage percentage target rather than to verify behavior. The tests exist to satisfy a metric, not to provide confidence.
+
+**How to spot it:**
+- Tests that assert trivially obvious things (e.g., `assert user.name == user.name`)
+- Every private method has a corresponding test accessed via reflection
+- 100% coverage but bugs still escape to production
+- Test suite takes minutes to pass but developers don't trust it
+
+**Fix:** Coverage is a diagnostic tool, not a goal. Use it to find untested gaps, not as a number to optimize. High 80s–90% emerges naturally from disciplined TDD. A test that only exists to push coverage up is worse than no test — it adds maintenance cost without adding confidence.
+
+```python
+# Bad — written for coverage, not for confidence
+def test_user_has_name():
+    user = User(name="Alice")
+    assert user.name is not None  # This verifies nothing meaningful
+
+# Good — written to verify a business rule
+def test_user_with_empty_name_raises_validation_error():
+    with pytest.raises(ValidationError, match="name cannot be empty"):
+        User(name="")
+```
+
+> See: https://martinfowler.com/bliki/TestCoverage.html
+
+## The Hard Test
+
+**What it is:** Not an anti-pattern in the test itself, but a signal from the test about the production code. When a test is painful, complex, or requires elaborate setup, the production code has a design problem.
+
+**How to spot it:**
+- Need to mock 5+ dependencies to test one class
+- Need to access private internals to verify behavior
+- Test requires a complex sequence of operations just to get to the state under test
+- You find yourself thinking "testing this would be too hard"
+
+**What it signals:**
+- Too many responsibilities in one class (SRP violation)
+- Hidden dependencies or tight coupling
+- Poor separation of concerns
+- Untestable architecture (e.g., side effects embedded in business logic)
+
+**Fix:** Resist the urge to skip the test or work around it with clever mocking. Instead, fix the production code design. Extract classes, inject dependencies, separate concerns. A hard test is a free design review — take the feedback.
+
+```python
+# Hard to test — service does too much
+class OrderService:
+    def process(self, order):
+        db = Database()          # hidden dependency
+        email = EmailClient()    # hidden dependency
+        self._validate(order)
+        db.save(order)
+        email.send_confirmation(order)
+        self._update_inventory(order)  # another responsibility
+
+# Easy to test — dependencies explicit, concerns separated
+class OrderService:
+    def __init__(self, repo: OrderRepository, notifier: Notifier):
+        self._repo = repo
+        self._notifier = notifier
+
+    def process(self, order: Order) -> OrderResult:
+        self._validate(order)
+        saved = self._repo.save(order)
+        self._notifier.notify(saved)
+        return saved
+```
+
+---
+
+## Further Reading
+
+- xUnit Patterns (Meszaros): http://xunitpatterns.com
+- Codepipes testing anti-patterns: https://blog.codepipes.com/testing/software-testing-antipatterns.html
+- Google SWE Book — Test Doubles: https://abseil.io/resources/swe-book/html/ch13.html