Cursor rule

1---
2description: Rust Testing strategy
3globs: "**/*.rs"
4alwaysApply: false
5---
6# Rust Testing Strategy
7 
8## Verification Commands
9 
10- When modifying Rust code, run clippy to detect issues:
11 
12```bash
13  cargo clippy --all-features --all-targets --workspace --no-deps
14```
15 
16- If changes affect the `hash-graph-api` crate or any representation influencing the public interface, regenerate the OpenAPI specifications:
17 
18```bash
19  cd libs/@local/graph/api
20  cargo run --bin openapi-spec-generator
21```
22 
23- Use `cargo doc --no-deps --all-features` to check documentation
24 
25## Test Execution
26 
27- Use `cargo-nextest` for running unit and integration tests
28- Use the default test runner for documentation tests
29- For comprehensive verification, run the complete test suite
30- Database seeding can be performed using yarn commands in the project's package.json
31 
32## Test Design Principles
33 
34- Test both happy paths and error conditions for each function
35- For each error case in your code, write a corresponding test
36- Test boundary conditions and edge cases explicitly
37- Include tests for invalid or malformed inputs
38- For streaming encoders/decoders, test partial data handling and buffer management
39- Aim for high test coverage but prioritize test quality over quantity
40- Structure tests following the Arrange-Act-Assert pattern
41 
42## Assertion Standards
43 
44- Use descriptive assertion messages that explain the expected behavior
45- All assertion messages (including `expect()`, `unwrap()` and `assert*()`) should follow the "should..." format:
46 
47```rust
48  // Good examples:
49  value.expect("should contain a valid configuration");
50  assert_eq!(result, expected, "Result should match the expected value");
51```
52 
53- Use `expect()` or `expect_err()` with clear messages instead of `unwrap()` or `unwrap_err()`
54- Prefer `assert_eq!` with custom messages over bare assertions when comparing values
55- When testing errors, assert on specific error types or message contents, not just that an error occurred
56- Balance assertions to verify functionality without creating brittle tests
57 
58## Test Organization
59 
60- Group related tests into appropriate modules
61- Use descriptive test names that explain the test scenario and expected outcome
62- Do not prefix test function names with `test_` (avoid `test::test_name` patterns)
63- Use helper functions to avoid code duplication in tests
64- Consider using parameterized tests for testing similar functionality with different inputs
65 
66## Test Code Quality
67 
68- Follow the same code quality standards in test code as in production code
69- Add appropriate assertions for array/slice access to avoid clippy warnings
70- Document test scenarios with clear comments explaining:
71  - The setup (input and environment)
72  - The action being tested
73  - The expected outcome
74  - Why the outcome is expected
75- Consider adding custom test utilities to simplify common testing patterns
76- Use the `json!` macro from `serde_json` instead of constructing JSON as raw strings
77 
78```rust
79// Bad:
80let json_str = "{\"name\":\"value\",\"nested\":{\"key\":42}}";
81 
82// Good:
83use serde_json::json;
84let json_value = json!({
85    "name": "value",
86    "nested": {
87        "key": 42
88    }
89});
90```
91 
92## Integration With Other Practices
93 
94- For documentation practices in tests, refer to the [Rust Documentation Practices](mdc:.cursor/rules/documenting-rust-code.mdc) file
95- For error handling in tests, refer to the [Rust Error Handling Practices](mdc:.cursor/rules/rust-error-handling.mdc) file
96