Skip to content

Commit d3bb1c8

Browse files
carlosedpcarlosedp
committed
feat: Add comprehensive tests to rebar3 diameter compiler plugin
- Introduced `flake.nix` and `flake.lock` for Nix package management. - Implemented the `rebar3_diameter_compiler` plugin to compile diameter `.dia` files. - Created a development shell with necessary tools for plugin development. - Added integration tests in `dia_tests.erl` covering compilation and dependency resolution. - Developed unit tests in `unit_tests.erl` for error handling, configuration parsing, and provider initialization. - Implemented error tests in `error_tests.erl` to handle malformed files and missing dependencies. - Added property-based tests in `property_tests.erl` to verify invariants and edge cases. - Included test coverage documentation in `TEST_COVERAGE.md`. - Created sample `.dia` files for testing various inheritance scenarios. - Enhanced error reporting in compilation commands for better debugging.
1 parent e3511e8 commit d3bb1c8

13 files changed

Lines changed: 1698 additions & 2 deletions

‎.github/copilot-instructions.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Copilot Instructions for rebar3_diameter_compiler
2+
3+
## Project Overview
4+
5+
This is a **rebar3 plugin** that compiles Diameter protocol dictionary files (`.dia`) into Erlang source code. It integrates with rebar3's build system as a provider plugin with compile and clean tasks.
6+
7+
### Architecture
8+
9+
- **Entry point**: `src/rebar3_diameter_compiler.erl` - Minimal wrapper that registers two providers
10+
- **Compile provider**: `src/compile_diameter.erl` - Core compilation logic with dependency resolution
11+
- **Clean provider**: `src/clean_diameter.erl` - Removes generated `.erl` and `.hrl` files
12+
- **Key mechanism**: Uses digraph for topological sorting of `@inherits` dependencies in `.dia` files
13+
14+
### Critical Data Flow
15+
16+
1. Discover `.dia` files in `dia/` directory using regex pattern `^(?!\\._).*\\.dia$`
17+
2. Parse each file to extract `@inherits` directives (binary pattern matching on `<<"@inherits">>`)
18+
3. Build dependency graph using `digraph` module
19+
4. Topologically sort files so inherited dictionaries compile first
20+
5. Generate `.erl` files (to `src/`) and `.hrl` files (to `include/`) via `diameter_codegen`
21+
6. Compile generated `.erl` to `.beam` and load into code path
22+
23+
## Developer Workflows
24+
25+
### Testing (59 tests across 4 modules)
26+
27+
```bash
28+
rebar3 eunit # Run all tests
29+
rebar3 eunit --module=unit_tests # Unit tests only
30+
rebar3 eunit --module=error_tests # Error handling tests
31+
rebar3 eunit --module=property_tests # Fuzz/stress tests
32+
rebar3 eunit --module=dia_tests # Integration tests
33+
GOLDEN_RUN=1 rebar3 eunit # Regenerate expected test outputs
34+
```
35+
36+
**Test structure**: Integration tests (`dia_tests.erl`) compile real rebar3 projects in `_build/test/lib/`. They use git-based plugin loading with `file://` URLs pointing to repo root.
37+
38+
**CI Testing**: Tests detect CI environments via `GITHUB_HEAD_REF` and `GITHUB_REF_NAME` environment variables for proper git branch handling. Integration tests capture full command output with exit codes for debugging failures.
39+
40+
### Code Quality
41+
42+
```bash
43+
rebar3 lint # edoc + format + xref
44+
rebar3 lint_all # + dialyzer + dialyzer_html
45+
rebar3 format # Format with erlfmt (100 char width)
46+
```
47+
48+
### Publishing
49+
50+
```bash
51+
rebar3 pub # eunit + edoc + format + hex cut
52+
rebar3 publish_hex # eunit + edoc + hex publish
53+
```
54+
55+
### Nix Development
56+
57+
```bash
58+
nix develop # Enter dev shell with Erlang + rebar3
59+
nix build # Build package
60+
nix run .#test # Run tests via Nix
61+
```
62+
63+
## Project-Specific Patterns
64+
65+
### Provider Registration Pattern
66+
67+
All providers follow this structure:
68+
69+
1. Export `init/1`, `do/1`, `format_error/1`
70+
2. Use `providers:create/1` with namespace `diameter` and module `?MODULE`
71+
3. Register via `rebar_state:add_provider/2`
72+
4. Dependency: `[{default, app_discovery}]` to ensure apps are discovered first
73+
74+
### Dependency Resolution Algorithm
75+
76+
**Key insight**: The `compile_order/3` function in `compile_diameter.erl` uses a sophisticated graph approach:
77+
78+
- Parses `.dia` files as binaries split by newlines to extract `@inherits` directives
79+
- Builds digraph where edges point FROM dependent TO dependency
80+
- Uses `digraph_utils:reachable/2` + `digraph_utils:subgraph/2` + `digraph_utils:topsort/1`
81+
- Filters by `dia_only_files` config option to compile subset of files
82+
- Returns `{ok, Order}` or `{error, Reason}` (circular deps return `false` from topsort)
83+
84+
### Configuration Options
85+
86+
Three rebar.config options (see `compile_diameter.erl` lines 147-152):
87+
88+
- `dia_opts` - Passed to `diameter_dict_util:parse/2` and `diameter_codegen:from_dict/4`
89+
- `dia_first_files` - Files to compile before dependency-ordered compilation
90+
- `dia_only_files` - Filter to compile only specific dictionaries (matched by basename)
91+
92+
### Test Patterns
93+
94+
- **Integration tests** (`dia_tests.erl`): Create temp rebar3 projects, setup git branches dynamically for CI
95+
- **Unit tests** (`unit_tests.erl`): Test provider init, graph algorithms, path handling
96+
- **Error tests** (`error_tests.erl`): Malformed files, encoding, circular deps
97+
- **Property tests** (`property_tests.erl`): Fuzz testing, stress tests (1000+ nodes), PropEr integration (optional)
98+
99+
**Testing anti-pattern**: Don't call providers directly. Integration tests use actual `rebar3 diameter compile` commands via `os:cmd/1`.
100+
101+
### EDoc Documentation
102+
103+
Heavy use of `@doc`, `@private`, `@param`, `@returns` tags. The `edoc_opts` in rebar.config generates docs to `doc/` with custom overview from `doc/overview.edoc`.
104+
105+
### Cross-OTP Compatibility
106+
107+
Tests filter OTP version differences like `-moduledoc(false).` (OTP 27+). See `filter_otp_differences/1` in `dia_tests.erl`.
108+
109+
## Key Files to Reference
110+
111+
- `src/compile_diameter.erl` lines 301-393: Complete dependency resolution algorithm
112+
- `test/dia_tests.erl` lines 88-222: CI-aware test setup with git branch detection
113+
- `rebar.config` lines 11-16: Custom command aliases pattern
114+
- `test/TEST_COVERAGE.md`: Comprehensive test documentation
115+
116+
## External Dependencies
117+
118+
- **diameter** (OTP standard library): Uses `diameter_dict_util` for parsing, `diameter_codegen` for code generation
119+
- **rebar3**: Provider API, state management, base_compiler
120+
- **digraph**: Dependency graph construction (standard library)
121+
- No external deps in `rebar.config` - pure OTP plugin
122+
123+
## Common Pitfalls
124+
125+
1. **Graph direction matters**: Edges go FROM dependent TO dependency, not vice versa
126+
2. **Binary parsing**: `.dia` files split by `<<"\n">>` and `<<"\r">>`, not strings
127+
3. **Test isolation**: Integration tests must use unique temp dirs with `erlang:unique_integer([positive])`
128+
4. **Provider hooks**: Use `{pre, [...]}` not `{post, [...]}` for compile/clean hooks
129+
5. **Circular deps**: `digraph_utils:topsort/1` returns `false` (not error tuple) for cycles

‎.github/workflows/erlang.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,10 @@ jobs:
4343
rebar3-version: ${{ matrix.rebar3 }}
4444

4545
- name: Run tests
46-
run: rebar3 eunit
46+
run: rebar3 eunit --cover
47+
48+
- name: Show coverage
49+
run: rebar3 cover --verbose
4750

4851
docs:
4952
runs-on: ubuntu-latest

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,8 @@ rebar3.crashdump
2121

2222
# Hex publishing artifacts
2323
*.tar
24+
25+
# Nix build results
26+
result
27+
result-*
28+
.direnv

‎TEST_IMPROVEMENTS.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Test Coverage Improvements Summary
2+
3+
## Overview
4+
Enhanced the rebar3_diameter_compiler plugin test suite from basic integration tests to comprehensive coverage including unit tests, error handling, property-based testing, and stress tests.
5+
6+
## Test Suite Growth
7+
- **Before**: 3 integration tests (compile, compile_only, compare)
8+
- **After**: 59 total tests across 4 test modules
9+
- **New Tests Added**: 56 tests
10+
11+
## New Test Modules
12+
13+
### 1. Unit Tests (`unit_tests.erl`) - 32 tests
14+
**Purpose**: Test individual components and functions in isolation
15+
16+
**Coverage Areas**:
17+
- Provider initialization (compile and clean providers)
18+
- Error message formatting
19+
- Configuration option parsing (`dia_opts`, `dia_first_files`, `dia_only_files`)
20+
- Path and filename operations
21+
- Dependency graph construction and topological sorting
22+
- File pattern matching with regex
23+
- Rebar3 state operations
24+
- List deduplication utilities
25+
- File operation setup helpers
26+
27+
**Key Test Categories**:
28+
- ✅ Provider registration and initialization
29+
- ✅ Configuration validation
30+
- ✅ Filename edge cases (empty paths, multiple dots, special characters)
31+
- ✅ Dependency graph algorithms (simple chains, diamonds, cycles)
32+
- ✅ Regex pattern matching for .dia files
33+
- ✅ Rebar3 state manipulation
34+
35+
### 2. Error Tests (`error_tests.erl`) - 14 tests
36+
**Purpose**: Verify robust error handling and edge cases
37+
38+
**Coverage Areas**:
39+
- Malformed .dia files (empty, comments-only, syntax errors)
40+
- Missing dependencies (non-existent inherited dictionaries)
41+
- File system errors (missing files, directories as files)
42+
- Circular dependency detection
43+
- Name conflicts (@name vs filename mismatches)
44+
- Character encoding (UTF-8 content)
45+
- File format edge cases (long lines, no trailing newlines, CRLF)
46+
47+
**Key Test Categories**:
48+
- ✅ Empty and minimal .dia files
49+
- ✅ Malformed dictionary syntax
50+
- ✅ Missing inherited dictionaries
51+
- ✅ Non-existent file handling
52+
- ✅ Directory/file confusion
53+
- ✅ Configuration errors
54+
- ✅ Circular inheritance detection
55+
- ✅ UTF-8 and encoding support
56+
- ✅ Line ending variations (Unix/Windows)
57+
58+
### 3. Property-Based Tests (`property_tests.erl`) - 10 tests
59+
**Purpose**: Verify invariants with randomized inputs
60+
61+
**Coverage Areas**:
62+
- Graph operation properties (vertex count preservation)
63+
- Path operation idempotence
64+
- List deduplication invariants
65+
- Fuzz testing (filename ops, proplists, digraph)
66+
- Topological sort correctness
67+
- Reachability invariants
68+
- Large-scale stress testing (1000+ node graphs)
69+
- Resource leak detection (many file operations)
70+
71+
**Key Test Categories**:
72+
- ✅ Property-based tests (with PropEr when available)
73+
- ✅ Fuzz testing with random inputs
74+
- ✅ Invariant verification
75+
- ✅ Stress testing (large graphs, many files)
76+
- ✅ Resource management
77+
78+
### 4. Integration Tests (`dia_tests.erl`) - 3 tests (existing)
79+
**Purpose**: End-to-end compilation testing
80+
81+
**Coverage Areas**:
82+
- Full rebar3 project compilation
83+
- Selective file compilation (`dia_only_files`)
84+
- Generated output validation
85+
- Cross-OTP version compatibility
86+
87+
## New Test Artifacts
88+
89+
### Test .dia Files
90+
- `qux.dia` - Tests single inheritance (depends on foo)
91+
- `complex.dia` - Tests multiple inheritance (depends on foo and bar)
92+
- Existing: `foo.dia`, `bar.dia`, `baz.dia`, `diameter_3gpp_base.dia`
93+
94+
### Documentation
95+
- `TEST_COVERAGE.md` - Comprehensive test documentation
96+
- Test running instructions
97+
- Coverage goals and CI/CD integration details
98+
99+
## Test Statistics
100+
101+
```
102+
Total Tests: 59
103+
├── Integration Tests: 3 (5%)
104+
├── Unit Tests: 32 (54%)
105+
├── Error Tests: 14 (24%)
106+
└── Property Tests: 10 (17%)
107+
108+
Test Execution Time: ~24 seconds (full suite)
109+
All Tests: PASSING ✅
110+
```
111+
112+
## Coverage Improvements
113+
114+
### Areas Now Tested
115+
1. **Provider System**
116+
- Initialization and registration
117+
- Command-line interface
118+
- Rebar3 integration
119+
120+
2. **Configuration Handling**
121+
- Option parsing and validation
122+
- Default value handling
123+
- Invalid configuration detection
124+
125+
3. **Dependency Resolution**
126+
- @inherits parsing
127+
- Graph construction
128+
- Topological sorting
129+
- Circular dependency detection
130+
- Multiple inheritance
131+
132+
4. **File Operations**
133+
- Pattern matching and discovery
134+
- Path manipulation
135+
- File I/O edge cases
136+
- Encoding handling
137+
138+
5. **Error Handling**
139+
- Malformed input files
140+
- Missing dependencies
141+
- File system errors
142+
- Configuration errors
143+
144+
6. **Robustness**
145+
- Fuzz testing
146+
- Large-scale stress tests
147+
- Resource leak prevention
148+
- Cross-platform compatibility
149+
150+
## Running Tests
151+
152+
### All Tests
153+
```bash
154+
rebar3 eunit
155+
```
156+
157+
### Specific Modules
158+
```bash
159+
rebar3 eunit --module=unit_tests
160+
rebar3 eunit --module=error_tests
161+
rebar3 eunit --module=property_tests
162+
rebar3 eunit --module=dia_tests
163+
```
164+
165+
### With Coverage Report
166+
```bash
167+
rebar3 cover -v
168+
```
169+
170+
### In Nix Development Shell
171+
```bash
172+
nix develop
173+
rebar3 eunit
174+
```
175+
176+
## Benefits
177+
178+
1. **Higher Confidence**: More comprehensive testing catches regressions early
179+
2. **Better Documentation**: Tests serve as usage examples
180+
3. **Easier Refactoring**: Unit tests enable safe code changes
181+
4. **Error Prevention**: Edge cases and error paths are validated
182+
5. **Cross-Platform**: Tests verify behavior across different systems
183+
6. **Performance**: Stress tests identify scaling issues
184+
185+
## Future Enhancements
186+
187+
Potential areas for further testing:
188+
- Performance benchmarks
189+
- Concurrency testing
190+
- Memory usage profiling
191+
- Integration with more Diameter applications
192+
- Custom codec testing
193+
- Watch mode testing (if implemented)
194+
195+
## Compatibility
196+
197+
- **Erlang/OTP**: 23+ (as per project requirements)
198+
- **PropEr**: Optional (property tests skip gracefully if unavailable)
199+
- **Platforms**: Linux, macOS, Windows (via test design)
200+
- **CI/CD**: GitHub Actions integration verified

0 commit comments

Comments
 (0)