mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-10 19:33:37 +08:00
docs(zh-CN): sync Chinese docs with latest upstream changes
This commit is contained in:
neo
502
docs/zh-CN/skills/rust-testing/SKILL.md
Normal file
502
docs/zh-CN/skills/rust-testing/SKILL.md
Normal file
@@ -0,0 +1,502 @@
|
||||
---
|
||||
name: rust-testing
|
||||
description: Rust测试模式，包括单元测试、集成测试、异步测试、基于属性的测试、模拟和覆盖率。遵循TDD方法学。
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Rust 测试模式
|
||||
|
||||
遵循 TDD 方法论编写可靠、可维护测试的全面 Rust 测试模式。
|
||||
|
||||
## 何时使用
|
||||
|
||||
* 编写新的 Rust 函数、方法或特征
|
||||
* 为现有代码添加测试覆盖率
|
||||
* 为性能关键代码创建基准测试
|
||||
* 为输入验证实现基于属性的测试
|
||||
* 在 Rust 项目中遵循 TDD 工作流
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. **识别目标代码** — 找到要测试的函数、特征或模块
|
||||
2. **编写测试** — 在 `#[cfg(test)]` 模块中使用 `#[test]`，使用 rstest 进行参数化测试，或使用 proptest 进行基于属性的测试
|
||||
3. **模拟依赖项** — 使用 mockall 来隔离被测单元
|
||||
4. **运行测试 (RED)** — 验证测试是否按预期失败
|
||||
5. **实现 (GREEN)** — 编写最少代码以通过测试
|
||||
6. **重构** — 改进代码同时保持测试通过
|
||||
7. **检查覆盖率** — 使用 cargo-llvm-cov，目标 80% 以上
|
||||
|
||||
## Rust 的 TDD 工作流
|
||||
|
||||
### RED-GREEN-REFACTOR 循环
|
||||
|
||||
```
|
||||
RED → Write a failing test first
|
||||
GREEN → Write minimal code to pass the test
|
||||
REFACTOR → Improve code while keeping tests green
|
||||
REPEAT → Continue with next requirement
|
||||
```
|
||||
|
||||
### Rust 中的分步 TDD
|
||||
|
||||
```rust
|
||||
// RED: Write test first, use todo!() as placeholder
|
||||
pub fn add(a: i32, b: i32) -> i32 { todo!() }
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
#[test]
|
||||
fn test_add() { assert_eq!(add(2, 3), 5); }
|
||||
}
|
||||
// cargo test → panics at 'not yet implemented'
|
||||
```
|
||||
|
||||
```rust
|
||||
// GREEN: Replace todo!() with minimal implementation
|
||||
pub fn add(a: i32, b: i32) -> i32 { a + b }
|
||||
// cargo test → PASS, then REFACTOR while keeping tests green
|
||||
```
|
||||
|
||||
## 单元测试
|
||||
|
||||
### 模块级测试组织
|
||||
|
||||
```rust
|
||||
// src/user.rs
|
||||
pub struct User {
|
||||
pub name: String,
|
||||
pub email: String,
|
||||
}
|
||||
|
||||
impl User {
|
||||
pub fn new(name: impl Into<String>, email: impl Into<String>) -> Result<Self, String> {
|
||||
let email = email.into();
|
||||
if !email.contains('@') {
|
||||
return Err(format!("invalid email: {email}"));
|
||||
}
|
||||
Ok(Self { name: name.into(), email })
|
||||
}
|
||||
|
||||
pub fn display_name(&self) -> &str {
|
||||
&self.name
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn creates_user_with_valid_email() {
|
||||
let user = User::new("Alice", "alice@example.com").unwrap();
|
||||
assert_eq!(user.display_name(), "Alice");
|
||||
assert_eq!(user.email, "alice@example.com");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rejects_invalid_email() {
|
||||
let result = User::new("Bob", "not-an-email");
|
||||
assert!(result.is_err());
|
||||
assert!(result.unwrap_err().contains("invalid email"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 断言宏
|
||||
|
||||
```rust
|
||||
assert_eq!(2 + 2, 4); // Equality
|
||||
assert_ne!(2 + 2, 5); // Inequality
|
||||
assert!(vec![1, 2, 3].contains(&2)); // Boolean
|
||||
assert_eq!(value, 42, "expected 42 but got {value}"); // Custom message
|
||||
assert!((0.1_f64 + 0.2 - 0.3).abs() < f64::EPSILON); // Float comparison
|
||||
```
|
||||
|
||||
## 错误与 Panic 测试
|
||||
|
||||
### 测试 `Result` 返回值
|
||||
|
||||
```rust
|
||||
#[test]
|
||||
fn parse_returns_error_for_invalid_input() {
|
||||
let result = parse_config("}{invalid");
|
||||
assert!(result.is_err());
|
||||
|
||||
// Assert specific error variant
|
||||
let err = result.unwrap_err();
|
||||
assert!(matches!(err, ConfigError::ParseError(_)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_succeeds_for_valid_input() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let config = parse_config(r#"{"port": 8080}"#)?;
|
||||
assert_eq!(config.port, 8080);
|
||||
Ok(()) // Test fails if any ? returns Err
|
||||
}
|
||||
```
|
||||
|
||||
### 测试 Panic
|
||||
|
||||
```rust
|
||||
#[test]
|
||||
#[should_panic]
|
||||
fn panics_on_empty_input() {
|
||||
process(&[]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[should_panic(expected = "index out of bounds")]
|
||||
fn panics_with_specific_message() {
|
||||
let v: Vec<i32> = vec![];
|
||||
let _ = v[0];
|
||||
}
|
||||
```
|
||||
|
||||
## 集成测试
|
||||
|
||||
### 文件结构
|
||||
|
||||
```text
|
||||
my_crate/
|
||||
├── src/
|
||||
│ └── lib.rs
|
||||
├── tests/ # Integration tests
|
||||
│ ├── api_test.rs # Each file is a separate test binary
|
||||
│ ├── db_test.rs
|
||||
│ └── common/ # Shared test utilities
|
||||
│ └── mod.rs
|
||||
```
|
||||
|
||||
### 编写集成测试
|
||||
|
||||
```rust
|
||||
// tests/api_test.rs
|
||||
use my_crate::{App, Config};
|
||||
|
||||
#[test]
|
||||
fn full_request_lifecycle() {
|
||||
let config = Config::test_default();
|
||||
let app = App::new(config);
|
||||
|
||||
let response = app.handle_request("/health");
|
||||
assert_eq!(response.status, 200);
|
||||
assert_eq!(response.body, "OK");
|
||||
}
|
||||
```
|
||||
|
||||
## 异步测试
|
||||
|
||||
### 使用 Tokio
|
||||
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn fetches_data_successfully() {
|
||||
let client = TestClient::new().await;
|
||||
let result = client.get("/data").await;
|
||||
assert!(result.is_ok());
|
||||
assert_eq!(result.unwrap().items.len(), 3);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn handles_timeout() {
|
||||
use std::time::Duration;
|
||||
let result = tokio::time::timeout(
|
||||
Duration::from_millis(100),
|
||||
slow_operation(),
|
||||
).await;
|
||||
|
||||
assert!(result.is_err(), "should have timed out");
|
||||
}
|
||||
```
|
||||
|
||||
## 测试组织模式
|
||||
|
||||
### 使用 `rstest` 进行参数化测试
|
||||
|
||||
```rust
|
||||
use rstest::{rstest, fixture};
|
||||
|
||||
#[rstest]
|
||||
#[case("hello", 5)]
|
||||
#[case("", 0)]
|
||||
#[case("rust", 4)]
|
||||
fn test_string_length(#[case] input: &str, #[case] expected: usize) {
|
||||
assert_eq!(input.len(), expected);
|
||||
}
|
||||
|
||||
// Fixtures
|
||||
#[fixture]
|
||||
fn test_db() -> TestDb {
|
||||
TestDb::new_in_memory()
|
||||
}
|
||||
|
||||
#[rstest]
|
||||
fn test_insert(test_db: TestDb) {
|
||||
test_db.insert("key", "value");
|
||||
assert_eq!(test_db.get("key"), Some("value".into()));
|
||||
}
|
||||
```
|
||||
|
||||
### 测试辅助函数
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// Creates a test user with sensible defaults.
|
||||
fn make_user(name: &str) -> User {
|
||||
User::new(name, &format!("{name}@test.com")).unwrap()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn user_display() {
|
||||
let user = make_user("alice");
|
||||
assert_eq!(user.display_name(), "alice");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用 `proptest` 进行基于属性的测试
|
||||
|
||||
### 基本属性测试
|
||||
|
||||
```rust
|
||||
use proptest::prelude::*;
|
||||
|
||||
proptest! {
|
||||
#[test]
|
||||
fn encode_decode_roundtrip(input in ".*") {
|
||||
let encoded = encode(&input);
|
||||
let decoded = decode(&encoded).unwrap();
|
||||
assert_eq!(input, decoded);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sort_preserves_length(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
|
||||
let original_len = vec.len();
|
||||
vec.sort();
|
||||
assert_eq!(vec.len(), original_len);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sort_produces_ordered_output(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
|
||||
vec.sort();
|
||||
for window in vec.windows(2) {
|
||||
assert!(window[0] <= window[1]);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义策略
|
||||
|
||||
```rust
|
||||
use proptest::prelude::*;
|
||||
|
||||
fn valid_email() -> impl Strategy<Value = String> {
|
||||
("[a-z]{1,10}", "[a-z]{1,5}")
|
||||
.prop_map(|(user, domain)| format!("{user}@{domain}.com"))
|
||||
}
|
||||
|
||||
proptest! {
|
||||
#[test]
|
||||
fn accepts_valid_emails(email in valid_email()) {
|
||||
assert!(User::new("Test", &email).is_ok());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用 `mockall` 进行模拟
|
||||
|
||||
### 基于特征的模拟
|
||||
|
||||
```rust
|
||||
use mockall::{automock, predicate::eq};
|
||||
|
||||
#[automock]
|
||||
trait UserRepository {
|
||||
fn find_by_id(&self, id: u64) -> Option<User>;
|
||||
fn save(&self, user: &User) -> Result<(), StorageError>;
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn service_returns_user_when_found() {
|
||||
let mut mock = MockUserRepository::new();
|
||||
mock.expect_find_by_id()
|
||||
.with(eq(42))
|
||||
.times(1)
|
||||
.returning(|_| Some(User { id: 42, name: "Alice".into() }));
|
||||
|
||||
let service = UserService::new(Box::new(mock));
|
||||
let user = service.get_user(42).unwrap();
|
||||
assert_eq!(user.name, "Alice");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn service_returns_none_when_not_found() {
|
||||
let mut mock = MockUserRepository::new();
|
||||
mock.expect_find_by_id()
|
||||
.returning(|_| None);
|
||||
|
||||
let service = UserService::new(Box::new(mock));
|
||||
assert!(service.get_user(99).is_none());
|
||||
}
|
||||
```
|
||||
|
||||
## 文档测试
|
||||
|
||||
### 可执行的文档
|
||||
|
||||
````rust
|
||||
/// Adds two numbers together.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use my_crate::add;
|
||||
///
|
||||
/// assert_eq!(add(2, 3), 5);
|
||||
/// assert_eq!(add(-1, 1), 0);
|
||||
/// ```
|
||||
pub fn add(a: i32, b: i32) -> i32 {
|
||||
a + b
|
||||
}
|
||||
|
||||
/// Parses a config string.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns `Err` if the input is not valid TOML.
|
||||
///
|
||||
/// ```no_run
|
||||
/// use my_crate::parse_config;
|
||||
///
|
||||
/// let config = parse_config(r#"port = 8080"#).unwrap();
|
||||
/// assert_eq!(config.port, 8080);
|
||||
/// ```
|
||||
///
|
||||
/// ```no_run
|
||||
/// use my_crate::parse_config;
|
||||
///
|
||||
/// assert!(parse_config("}{invalid").is_err());
|
||||
/// ```
|
||||
pub fn parse_config(input: &str) -> Result<Config, ParseError> {
|
||||
todo!()
|
||||
}
|
||||
````
|
||||
|
||||
## 使用 Criterion 进行基准测试
|
||||
|
||||
```toml
|
||||
# Cargo.toml
|
||||
[dev-dependencies]
|
||||
criterion = { version = "0.5", features = ["html_reports"] }
|
||||
|
||||
[[bench]]
|
||||
name = "benchmark"
|
||||
harness = false
|
||||
```
|
||||
|
||||
```rust
|
||||
// benches/benchmark.rs
|
||||
use criterion::{black_box, criterion_group, criterion_main, Criterion};
|
||||
|
||||
fn fibonacci(n: u64) -> u64 {
|
||||
match n {
|
||||
0 | 1 => n,
|
||||
_ => fibonacci(n - 1) + fibonacci(n - 2),
|
||||
}
|
||||
}
|
||||
|
||||
fn bench_fibonacci(c: &mut Criterion) {
|
||||
c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
|
||||
}
|
||||
|
||||
criterion_group!(benches, bench_fibonacci);
|
||||
criterion_main!(benches);
|
||||
```
|
||||
|
||||
## 测试覆盖率
|
||||
|
||||
### 运行覆盖率
|
||||
|
||||
```bash
|
||||
# Install: cargo install cargo-llvm-cov (or use taiki-e/install-action in CI)
|
||||
cargo llvm-cov # Summary
|
||||
cargo llvm-cov --html # HTML report
|
||||
cargo llvm-cov --lcov > lcov.info # LCOV format for CI
|
||||
cargo llvm-cov --fail-under-lines 80 # Fail if below threshold
|
||||
```
|
||||
|
||||
### 覆盖率目标
|
||||
|
||||
| 代码类型 | 目标 |
|
||||
|-----------|--------|
|
||||
| 关键业务逻辑 | 100% |
|
||||
| 公共 API | 90%+ |
|
||||
| 通用代码 | 80%+ |
|
||||
| 生成的 / FFI 绑定 | 排除 |
|
||||
|
||||
## 测试命令
|
||||
|
||||
```bash
|
||||
cargo test # Run all tests
|
||||
cargo test -- --nocapture # Show println output
|
||||
cargo test test_name # Run tests matching pattern
|
||||
cargo test --lib # Unit tests only
|
||||
cargo test --test api_test # Integration tests only
|
||||
cargo test --doc # Doc tests only
|
||||
cargo test --no-fail-fast # Don't stop on first failure
|
||||
cargo test -- --ignored # Run ignored tests
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
**应该做：**
|
||||
|
||||
* 先写测试 (TDD)
|
||||
* 使用 `#[cfg(test)]` 模块进行单元测试
|
||||
* 测试行为，而非实现
|
||||
* 使用描述性测试名称来解释场景
|
||||
* 为了更好的错误信息，优先使用 `assert_eq!` 而非 `assert!`
|
||||
* 在返回 `Result` 的测试中使用 `?` 以获得更清晰的错误输出
|
||||
* 保持测试独立 — 没有共享的可变状态
|
||||
|
||||
**不应该做：**
|
||||
|
||||
* 在可以测试 `Result::is_err()` 时使用 `#[should_panic]`
|
||||
* 模拟所有内容 — 在可行时优先考虑集成测试
|
||||
* 忽略不稳定的测试 — 修复或隔离它们
|
||||
* 在测试中使用 `sleep()` — 使用通道、屏障或 `tokio::time::pause()`
|
||||
* 跳过错误路径测试
|
||||
|
||||
## CI 集成
|
||||
|
||||
```yaml
|
||||
# GitHub Actions
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
components: clippy, rustfmt
|
||||
|
||||
- name: Check formatting
|
||||
run: cargo fmt --check
|
||||
|
||||
- name: Clippy
|
||||
run: cargo clippy -- -D warnings
|
||||
|
||||
- name: Run tests
|
||||
run: cargo test
|
||||
|
||||
- uses: taiki-e/install-action@cargo-llvm-cov
|
||||
|
||||
- name: Coverage
|
||||
run: cargo llvm-cov --fail-under-lines 80
|
||||
```
|
||||
|
||||
**记住**：测试就是文档。它们展示了你的代码应如何使用。清晰编写并保持更新。
|
||||
Reference in New Issue
Block a user