Skip to content

Commit ec0e792

Browse files
HJLebbinkHJLebbink
authored
refactor: consolidate codebase structure and add testing infrastructure (#194)
Reorganize project structure to improve maintainability and add comprehensive testing documentation and tooling support.
1 parent f4b4c90 commit ec0e792

File tree

193 files changed

+7085
-594
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

193 files changed

+7085
-594
lines changed

‎.claude/QUICKSTART.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Quick Start: Test Coverage Commands
2+
3+
## Setup (One-time)
4+
5+
Install the coverage tool:
6+
```bash
7+
cargo install cargo-llvm-cov
8+
```
9+
10+
This takes a few minutes but only needs to be done once.
11+
12+
## Using the Commands
13+
14+
### Check Coverage (Read-only)
15+
16+
Simply type in your Claude Code chat:
17+
```
18+
/check-coverage
19+
```
20+
21+
This will:
22+
- Run coverage analysis
23+
- Show you a detailed report
24+
- Tell you exactly what needs testing
25+
- **Not make any changes to your code**
26+
27+
### Generate Tests (Auto-write)
28+
29+
Type in your Claude Code chat:
30+
```
31+
/test-coverage
32+
```
33+
34+
This will:
35+
- Run coverage analysis
36+
- Identify gaps
37+
- **Automatically create test files**
38+
- Write tests following project patterns
39+
- Verify tests compile and run
40+
- Report on coverage improvement
41+
42+
## Example Session
43+
44+
**You:** `/check-coverage`
45+
46+
**Claude:**
47+
```
48+
Coverage Report:
49+
- Overall: 78.5%
50+
- src/madmin/builders/metrics.rs: 45.2% (missing error path tests)
51+
- src/madmin/response/kms_status.rs: 67.8% (missing JSON parse error test)
52+
53+
Recommendations:
54+
1. Add test for metrics builder with invalid parameters
55+
2. Test KMS status response with malformed JSON
56+
```
57+
58+
**You:** `/test-coverage`
59+
60+
**Claude:**
61+
```
62+
Analyzing coverage... Installing cargo-llvm-cov...
63+
Running coverage analysis...
64+
65+
Identified 5 uncovered code paths:
66+
1. src/madmin/builders/metrics.rs:85-92 (error handling)
67+
2. src/madmin/response/kms_status.rs:34-38 (JSON parse error)
68+
...
69+
70+
Creating tests:
71+
✓ Created tests/madmin/test_metrics_errors.rs
72+
✓ Created tests/madmin/test_kms_errors.rs
73+
✓ Updated tests/madmin/mod.rs
74+
75+
Running tests...
76+
✓ All 48 tests passing
77+
78+
New coverage: 95.2% (+16.7%)
79+
80+
Remaining gaps:
81+
- src/madmin/types/kms.rs:45 (trivial getter)
82+
```
83+
84+
## Tips
85+
86+
1. **Run `/check-coverage` frequently** - It's fast and shows what needs work
87+
2. **Use `/test-coverage` for bulk work** - When you've added multiple APIs
88+
3. **Review generated tests** - They follow patterns but may need refinement
89+
4. **Some tests will be ignored** - If they need special environment (distributed mode, KMS, etc.)
90+
91+
## Troubleshooting
92+
93+
**"cargo-llvm-cov not found"**
94+
- Run: `cargo install cargo-llvm-cov`
95+
- Wait for installation to complete
96+
97+
**"Tests are failing"**
98+
- Check if MinIO server is running
99+
- Verify credentials in environment variables
100+
- Some tests are marked `#[ignore]` on purpose
101+
102+
**"Coverage percentage seems wrong"**
103+
- Make sure you're testing the right code (`--lib --tests`)
104+
- Excluded files (like generated code) won't affect percentage
105+
106+
## What Gets Tested
107+
108+
The commands focus on:
109+
- ✅ `src/madmin/` - All MinIO Admin API code
110+
- ✅ `src/s3/` - All S3 API code
111+
- ✅ Public API methods
112+
- ✅ Error handling paths
113+
- ✅ Builder patterns
114+
- ✅ Response parsing
115+
- ✅ Network error scenarios
116+
- ❌ Test files themselves (not counted in coverage)
117+
- ❌ Generated code (has marker comments)
118+
119+
## Tracking Files
120+
121+
After generating tests, the agent updates:
122+
- **`tests/TEST_COVERAGE.md`** - Overall statistics and coverage by API category
123+
- **`tests/API_TEST_MATRIX.md`** - Detailed test-to-API mappings

‎.claude/README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Claude Code Commands for MinIO Rust SDK
2+
3+
This directory contains custom slash commands for working with the MinIO Rust SDK project.
4+
5+
## Available Commands
6+
7+
### `/check-coverage`
8+
Analyzes test coverage and provides a detailed report without making changes.
9+
10+
**Usage:**
11+
```
12+
/check-coverage
13+
```
14+
15+
**What it does:**
16+
- Runs `cargo tarpaulin` to measure code coverage
17+
- Shows overall coverage percentage
18+
- Lists files with incomplete coverage
19+
- Identifies specific uncovered lines and functions
20+
- Provides recommendations for missing tests
21+
22+
**When to use:**
23+
- Before writing new tests to see what needs coverage
24+
- After implementing new features to verify they're tested
25+
- During code review to ensure quality standards
26+
27+
---
28+
29+
### `/test-coverage`
30+
Actively generates tests to achieve 100% code coverage.
31+
32+
**Usage:**
33+
```
34+
/test-coverage
35+
```
36+
37+
**What it does:**
38+
- Runs coverage analysis (same as `/check-coverage`)
39+
- Identifies uncovered code paths in both madmin and s3 modules
40+
- Automatically generates test files following project patterns
41+
- Adds tests to appropriate directories:
42+
- `tests/madmin/` for Admin API tests
43+
- `tests/` for S3 API tests
44+
- Registers new test modules appropriately
45+
- Verifies tests compile and run
46+
- Updates tracking files (`TEST_COVERAGE.md` and `API_TEST_MATRIX.md`)
47+
- Re-checks coverage to confirm improvement
48+
49+
**When to use:**
50+
- When you want to quickly boost test coverage
51+
- After implementing multiple new APIs without tests
52+
- To generate test scaffolding that you can then refine
53+
54+
**Note:** Generated tests follow project conventions:
55+
- Proper copyright headers
56+
- Async tokio tests
57+
- `#[ignore]` attribute for environment-dependent tests
58+
- Clear assertions and output messages
59+
60+
---
61+
62+
## Installing Coverage Tools
63+
64+
### Option 1: cargo-tarpaulin (Linux, macOS)
65+
```bash
66+
cargo install cargo-tarpaulin
67+
```
68+
69+
### Option 2: cargo-llvm-cov (Windows, cross-platform)
70+
```bash
71+
cargo install cargo-llvm-cov
72+
```
73+
74+
Then modify the commands to use:
75+
```bash
76+
cargo llvm-cov --lib --tests --lcov --output-path target/coverage/lcov.info
77+
```
78+
79+
---
80+
81+
## Coverage Goals
82+
83+
For the MinIO Rust SDK:
84+
- **Target:** 100% coverage for `src/madmin` and `src/s3` modules
85+
- **Focus Areas:**
86+
- Public API methods
87+
- Error handling paths
88+
- Builder pattern combinations
89+
- JSON parsing edge cases
90+
- Network error scenarios
91+
- Validation logic
92+
- **Acceptable Gaps:**
93+
- Generated code (with proper headers indicating so)
94+
- Trivial getters/setters
95+
- Debug implementations
96+
97+
## Tracking Files
98+
99+
The project maintains detailed tracking documents:
100+
- **`tests/TEST_COVERAGE.md`** - Statistics, coverage percentages, and API implementation status
101+
- **`tests/API_TEST_MATRIX.md`** - Detailed mapping of which test files exercise which APIs
102+
103+
The `/test-coverage` command automatically updates these files after generating tests.
104+
105+
---
106+
107+
## Example Workflow
108+
109+
1. **Check current coverage:**
110+
```
111+
/check-coverage
112+
```
113+
114+
2. **Review the report and decide:**
115+
- If gaps are small, write tests manually
116+
- If gaps are large, use `/test-coverage` to generate scaffolding
117+
118+
3. **Generate tests automatically:**
119+
```
120+
/test-coverage
121+
```
122+
123+
4. **Review and refine generated tests:**
124+
- Check that tests make sense for the functionality
125+
- Add more specific assertions if needed
126+
- Un-ignore tests that can actually run in your environment
127+
128+
5. **Run tests:**
129+
```bash
130+
cargo test --test test_madmin
131+
```
132+
133+
6. **Re-check coverage:**
134+
```
135+
/check-coverage
136+
```
137+
138+
---
139+
140+
## Tips
141+
142+
- Run `/check-coverage` frequently during development
143+
- Use `/test-coverage` when you have multiple new APIs without tests
144+
- Always review auto-generated tests for correctness
145+
- Some tests will be marked `#[ignore]` - review these to determine if they can be enabled
146+
- Generated tests follow the patterns in existing test files

‎.claude/commands/check-coverage.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Check Test Coverage
2+
3+
Analyze code coverage for the MinIO Rust SDK and provide a detailed report.
4+
5+
## Your Task
6+
7+
1. **Install cargo-llvm-cov if needed**
8+
- Check if llvm-cov is installed: `cargo llvm-cov --version`
9+
- If not installed: `cargo install cargo-llvm-cov`
10+
- This tool works well on Windows and all platforms
11+
12+
2. **Run Coverage Analysis**
13+
- First try: `cargo llvm-cov --lib --tests` (includes unit tests only)
14+
- Try to also include integration tests: `cargo llvm-cov --all-targets --tests`
15+
- For HTML report: `cargo llvm-cov --lib --tests --html --output-dir target/coverage`
16+
- For detailed output: `cargo llvm-cov --lib --tests --text`
17+
- Focus on library code, not test code itself
18+
- **Important**: Integration tests in `tests/` directory may cover API functions and client operations
19+
20+
3. **Parse and Present Results**
21+
- Show overall coverage percentage (from both unit and integration tests)
22+
- List files with their coverage percentages
23+
- Identify files/functions with <100% coverage
24+
- Highlight critical uncovered code paths in `src/madmin` and `src/s3`
25+
- Separate coverage by module (madmin vs s3)
26+
- **Note**: Report which coverage comes from unit tests vs integration tests
27+
- Call out API/client methods that are covered by integration tests
28+
29+
4. **Provide Actionable Report**
30+
Present findings in this format:
31+
32+
```
33+
## Coverage Summary
34+
- Overall: XX.XX% (from unit + integration tests combined)
35+
- Unit Test Coverage: XX.XX%
36+
- Integration Test Coverage: XX.XX%
37+
- Lines covered: XXXX / XXXX
38+
- Functions covered: XXX / XXX
39+
40+
### Module Breakdown
41+
- src/madmin: XX.XX% (XXXX/XXXX lines) [Unit XX% / Integration XX%]
42+
- src/s3: XX.XX% (XXXX/XXXX lines) [Unit XX% / Integration XX%]
43+
44+
## API/Client Methods Covered by Integration Tests
45+
- src/s3/client/put_object.rs - covered by integration tests
46+
- src/s3/response/list_objects.rs - covered by integration tests
47+
- [List all methods with integration test coverage]
48+
49+
## Files Below 100% Coverage
50+
51+
### MinIO Admin (madmin)
52+
#### src/madmin/builders/some_file.rs (XX.XX%)
53+
- Line 45-52: Error handling path not tested (both unit and integration)
54+
- Line 78: Builder method combination not covered
55+
56+
#### src/madmin/response/other_file.rs (XX.XX%)
57+
- Line 23-25: JSON parsing error path missing test
58+
59+
### S3 API (s3)
60+
#### src/s3/client.rs (XX.XX%)
61+
- Line 123-130: Error handling for network failures
62+
- Line 245: Retry logic not tested
63+
64+
#### src/s3/args/some_arg.rs (XX.XX%)
65+
- Line 67-70: Validation edge case
66+
67+
## Recommendations
68+
1. [madmin] Add test for error case in some_file.rs:45-52
69+
2. [madmin] Test builder method combinations in some_file.rs:78
70+
3. [s3] Add network failure test in client.rs:123-130
71+
4. [s3] Test validation edge case in args/some_arg.rs:67-70
72+
5. Investigate which integration tests are failing and fix them to improve coverage
73+
```
74+
75+
5. **Suggest Next Steps**
76+
- Recommend which tests to write first (prioritize critical paths)
77+
- Indicate which API methods ARE covered by integration tests vs which are not
78+
- Note which integration tests are failing/skipped and why
79+
- Suggest whether to run `/test-coverage` to auto-generate tests for uncovered paths
80+
- Identify if any coverage gaps are in trivial code that can be ignored
81+
82+
Do not make any code changes - only analyze and report.

0 commit comments

Comments
 (0)