minio-rs/docs/TESTING_STRATEGY.md

# MinIO Rust SDK Testing Strategy

## Overview

The MinIO Rust SDK uses a comprehensive testing approach combining unit tests, property-based tests, and integration tests to ensure reliability and correctness.

## Test Categories

### 1. Unit Tests (Primary Focus)

**Location:** `src/madmin/types/*.rs`, inline `#[cfg(test)]` modules

**Purpose:** Test individual components in isolation
- Type serialization/deserialization
- Builder pattern correctness
- Response parsing
- Validation logic

**Coverage Goal:** >90% for library code

**Example:**
```rust
#[test]
fn test_batch_job_type_serialization() {
    let job_type = BatchJobType::Replicate;
    let json = serde_json::to_string(&job_type).unwrap();
    assert_eq!(json, "\"replicate\"");
}
```

### 2. Error Path Tests

**Location:** `src/madmin/types/error_tests.rs`

**Purpose:** Verify error handling and edge cases
- Invalid JSON deserialization
- Missing required fields
- Type mismatches
- Boundary conditions
- Unicode and special characters
- Malformed data

**Coverage Goal:** All error paths in critical code

**Example:**
```rust
#[test]
fn test_invalid_json_batch_job_type() {
    let invalid_json = "\"invalid_type\"";
    let result: Result<BatchJobType, _> = serde_json::from_str(invalid_json);
    assert!(result.is_err(), "Should fail on invalid batch job type");
}
```

### 3. Property-Based Tests

**Location:** `src/madmin/builders/property_tests.rs`

**Tool:** `quickcheck` crate

**Purpose:** Test properties that should hold for arbitrary inputs
- Builder idempotence
- Validation consistency
- No panics on valid inputs
- Encoding/decoding round-trips

**Coverage Goal:** Key invariants and properties

**Example:**
```rust
quickcheck! {
    fn prop_bucket_name_no_panic(name: String) -> TestResult {
        if name.is_empty() {
            return TestResult::discard();
        }
        let _result = validate_bucket_name(&name);
        TestResult::passed()
    }
}
```

### 4. Integration Tests

**Location:** `tests/` directory

**Purpose:** Test end-to-end workflows with live MinIO server
- Client initialization
- Request execution
- Response handling
- Multi-step operations

**Coverage Goal:** Critical user workflows

**Note:** Integration tests are **NOT** counted in unit test coverage metrics as they require external infrastructure.

**Example:**
```rust
#[tokio::test]
#[ignore] // Run only when MinIO server is available
async fn test_list_buckets() {
    let client = create_test_client();
    let buckets = client.list_buckets().send().await.unwrap();
    assert!(buckets.buckets.len() >= 0);
}
```

## What NOT to Test

### 1. Client Execution Methods
- Methods in `src/madmin/client/` that call `.send()`
- These require live server and belong in integration tests
- Focus unit tests on request building, not execution

### 2. Trivial Code
- Simple getter/setter methods
- Derived trait implementations (Debug, Clone, etc.)
- Pass-through wrapper functions

### 3. External Dependencies
- `reqwest` HTTP client behavior
- `serde_json` serialization correctness
- `tokio` runtime functionality

## Test Organization

### File Structure
```
src/
├── madmin/
│   ├── types/
│   │   ├── user.rs              # Type definitions + inline tests
│   │   ├── batch.rs             # Type definitions + inline tests
│   │   └── error_tests.rs       # Centralized error path tests
│   ├── builders/
│   │   ├── user_management/     # Builder implementations
│   │   └── property_tests.rs    # Property-based tests
│   └── client/                  # NO unit tests (integration only)
tests/
└── integration_tests.rs         # End-to-end tests (ignored by default)
```

### Test Naming Conventions

**Unit Tests:**
- `test_<functionality>_<scenario>`
- Example: `test_user_serialization_with_utf8`

**Error Tests:**
- `test_<error_condition>`
- Example: `test_invalid_json_batch_job_type`

**Property Tests:**
- `prop_<property_being_tested>`
- Example: `prop_builder_idempotent`

## Running Tests

### All Tests
```bash
cargo test
```

### Unit Tests Only (Fast)
```bash
cargo test --lib
```

### Specific Test Module
```bash
cargo test --lib types::error_tests
```

### Property-Based Tests
```bash
cargo test --lib property_tests
```

### Integration Tests (Requires MinIO Server)
```bash
cargo test --test integration_tests -- --ignored
```

### Coverage Report
```bash
cargo llvm-cov --lib --tests --html --output-dir target/coverage
```

## Coverage Goals

### Overall Target: 85%+

**By Module:**
- `src/madmin/types/`: 95%+ (high value, easy to test)
- `src/madmin/builders/`: 90%+ (core functionality)
- `src/madmin/response/`: 90%+ (parsing critical)
- `src/madmin/client/`: 20%+ (mostly integration tests)
- `src/s3/`: 85%+ (established S3 client)

### Acceptable Gaps
- Client method bodies (integration test coverage)
- Error display formatting
- Debug implementations
- Example code in doc comments

## Adding New Tests

### For New Type Definitions

1. Add inline serialization test
2. Add to error_tests.rs for edge cases
3. Consider property test if validation exists

### For New Builders

1. Test required parameter validation
2. Test optional parameter combinations
3. Add property test for invariants
4. Verify request URL/headers/body

### For New Response Types

1. Test successful parsing with sample JSON
2. Test error cases (missing fields, wrong types)
3. Test optional field handling

## Continuous Integration

### Pre-Commit Checklist
```bash
cargo fmt --all --check
cargo clippy -- -D warnings
cargo test --lib
```

### CI Pipeline
```yaml
- Run: cargo test --lib --all-features
- Coverage: cargo llvm-cov --lib --tests
- Minimum: 85% coverage required
```

## Best Practices

### DO:
- ✅ Test error paths explicitly
- ✅ Use property tests for validation logic
- ✅ Test edge cases (empty, null, oversized)
- ✅ Keep tests focused and independent
- ✅ Use descriptive test names

### DON'T:
- ❌ Test external library behavior
- ❌ Require live server for unit tests
- ❌ Test implementation details
- ❌ Write flaky tests with timeouts
- ❌ Duplicate coverage across test types

## Debugging Test Failures

### View Detailed Output
```bash
cargo test --lib -- --nocapture test_name
```

### Run Single Test
```bash
cargo test --lib test_name -- --exact
```

### Debug Coverage Gaps
```bash
cargo llvm-cov --lib --tests --html
# Open target/coverage/index.html
```

## Maintenance

### Regular Tasks
- Review coverage reports monthly
- Update tests when APIs change
- Remove obsolete tests
- Refactor duplicated test code

### When Coverage Drops
1. Identify uncovered code with llvm-cov HTML report
2. Assess if coverage gap is acceptable (client methods, trivial code)
3. Add targeted tests for critical uncovered paths
4. Document intentional coverage exclusions

## Resources

- [Rust Book - Testing](https://doc.rust-lang.org/book/ch11-00-testing.html)
- [quickcheck Documentation](https://docs.rs/quickcheck/)
- [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov)

## Questions?

For testing strategy questions, see:
- [CONTRIBUTING.md](CONTRIBUTING.md) - General contribution guidelines
- [CLAUDE.md](CLAUDE.md) - Code quality standards