Skip to content
Merged
104 changes: 104 additions & 0 deletions BREAKINGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ This document outlines all breaking changes introduced in CTBase v0.18.0-beta co
- [Exception System Overhaul](#exception-system-overhaul)
- [Module Reorganization](#module-reorganization)
- [Extension System Introduction](#extension-system-introduction)
- [TestRunner Enhancements](#testrunner-enhancements)
- [API Changes](#api-changes)
- [Dependency Updates](#dependency-updates)
- [Migration Guide](#migration-guide)
Expand Down Expand Up @@ -234,6 +235,109 @@ CTBase.Unicode.ctindice(1)

---

## TestRunner Enhancements

### 🚨 New Extension Features

The TestRunner extension has been significantly enhanced with advanced capabilities for test execution and progress tracking.

#### Progress Bar System Changes

The progress bar implementation has been completely rewritten with adaptive width:

```julia
# v0.18.0-beta (basic progress)
[████████████░░░░░░░░░░] ✓ [08/19] suite/exceptions/test_display.jl (2.5s)

# v0.18.0-beta.1 (adaptive width)
[████████░░░░░░░░░░] ✓ [08/19] suite/exceptions/test_display.jl (2.5s)
[████████████████████] ✓ [19/19] suite/exceptions/test_exceptions.jl (0.6s)
```

#### Enhanced Failure Detection

The failure detection mechanism is now more robust and accurate:

```julia
# v0.18.0-beta (unreliable)
# @test failures sometimes showed as success

# v0.18.0-beta.1 (robust detection)
# Correctly detects both exceptions and @test assertion failures
```

#### Path Prefix Stripping

Users can now use `test/suite` and `suite` interchangeably:

```julia
# v0.18.0-beta (explicit paths required)
julia --project -e 'using Pkg; Pkg.test(; test_args=["suite/exceptions"])'

# v0.18.0-beta.1 (automatic stripping)
julia --project -e 'using Pkg; Pkg.test(; test_args=["test/suite"])' # Same result
```

#### Callback System Overhaul

The callback system has been enhanced with rich context information:

```julia
# v0.18.0-beta (basic callbacks)
on_test_done = info -> println("Done: $(info.status)")

# v0.18.0-beta.1 (rich context)
on_test_done = info -> begin
if info.status == :error || info.status == :test_failed
println("❌ FAILED: $(info.spec)")
else
println("✓ Success: $(info.spec)")
end
end
```

#### Directory Protection

The system now prevents ambiguous directory structures:

```julia
# v0.18.0-beta (allowed)
test/
├── test/ # This would cause ambiguity with prefix stripping

# v0.18.0-beta.1 (protected)
ERROR: A subdirectory "test" exists inside the test directory
```

### 📚 Documentation Improvements

#### Docstring Standards Compliance

All TestRunner functions now follow the project's documentation standards:

```julia
"""
$(TYPEDSIGNATURES)
Run tests with configurable file/function name builders...

# Arguments
- `args::AbstractVector{<:AbstractString}`: Command-line arguments...
```

#### Cross-Reference Resolution

All internal references now use fully qualified names to prevent header conflicts:

```julia
# v0.18.0-beta (conflicts)
See also: [`TestRunInfo`](@ref) # Header conflicts

# v0.18.0-beta.1 (resolved)
See also: [`TestRunner.TestRunInfo`](@ref)
```

---

## Dependency Updates

### 🚨 Version Requirements
Expand Down
193 changes: 193 additions & 0 deletions CHANGELOGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,199 @@ This major release represents a significant investment in code quality, develope

---

## [0.18.0-beta.1] - 2025-02-09

### 🚀 TestRunner Enhancements

#### **Advanced Progress Bar System**
- **Adaptive bar width**: Width equals total for ≤20 tests, fixed at 20 for >20 tests
- **Visual consistency**: Uses `█` (filled) and `░` (empty) characters without gaps
- **Smart failure detection**: Correctly detects both exceptions and `@test` assertion failures
- **Zero-padded indices**: Aligned test numbers for better readability

#### **Robust Failure Detection**
- **Before/after results scanning**: Compares testset results before and after eval
- **Recursive failure detection**: Scans nested testsets for `Test.Fail` and `Test.Error`
- **More reliable than `anynonpass`**: Works regardless of testset completion timing

#### **Enhanced User Experience**
- **Path prefix stripping**: Users can write `test/suite` or `suite` interchangeably
- **Guard against conflicts**: Prevents `test/` subdirectory in test directory
- **Comprehensive callbacks**: `on_test_start` and `on_test_done` with `TestRunInfo` context
- **Configurable progress**: Built-in progress bar with option for custom callbacks

#### **Professional Documentation**
- **Complete docstring overhaul**: All functions follow project documentation standards
- **Safe, runnable examples**: All examples use `julia-repl` with proper imports
- **Cross-reference resolution**: Fully qualified `@ref` links to prevent header conflicts
- **API reference reorganization**: Clean separation in `src/api/` without prefixes

### 📈 Documentation Improvements

#### **Better Organization**
- **User guides in `src/guide/`**: Clear separation from API reference
- **API reference in `src/api/`**: Auto-generated with clean filenames
- **Updated navigation**: Changed "Tutorials" to "User Guides" for clarity
- **Fixed cleanup**: Generated API files properly removed after build

### 🔧 Technical Improvements

#### **Code Quality**
- **Fixed `@ref` conflicts**: All TestRunner references now use fully qualified names
- **Enhanced error handling**: Better detection and reporting of test failures
- **Improved type safety**: Comprehensive type annotations throughout
- **Memory optimization**: Efficient progress bar rendering and failure detection

---

## [0.18.0-beta] - 2025-02-04

### 🚀 Major Features

#### **Modular Architecture Overhaul**
- **Complete reorganization** of the codebase into thematic modules:

```text
src/
├── Core/ # Fundamental types and utilities
├── Exceptions/ # Enhanced error handling system
├── Unicode/ # Unicode character utilities
├── Descriptions/ # Description management
└── Extensions/ # Extension system with tag-based dispatch
```

- **Improved maintainability** through clear separation of concerns
- **Better testability** with isolated module boundaries

#### **Enhanced Exception System**

- **New exception types** with rich context:
- `PreconditionError`: Replaces `UnauthorizedCall` for state-related errors
- `ParsingError`: For syntax and structure validation errors
- `AmbiguousDescription`: Enhanced with diagnostic capabilities
- `ExtensionError`: Improved with feature and context information
- **Rich error messages** with optional fields for suggestions, context, and diagnostics
- **User-friendly display** with emojis and structured formatting
- **Better debugging experience** with detailed error context

#### **Professional Extension System**

- **Tag-based dispatch** for extension points:
- `AbstractDocumenterReferenceTag` / `DocumenterReferenceTag`
- `AbstractCoveragePostprocessingTag` / `CoveragePostprocessingTag`
- `AbstractTestRunnerTag` / `TestRunnerTag`
- **Three core extensions**:
- `DocumenterReference`: API documentation generation
- `CoveragePostprocessing`: Test coverage analysis and reporting
- `TestRunner`: Advanced test execution with glob patterns
- **Clean separation** between extension points and implementations

#### **Advanced Test Runner**

- **Glob pattern support** for test selection
- **Configurable filename/function name builders**
- **Dry run mode** for test planning
- **Recursive test discovery** in subdirectories
- **Integration with Julia's test ecosystem**

### 📈 Enhancements

#### **Documentation Improvements**

- **Complete documentation rewrite** with modular tutorials
- **API reference generation** with automatic categorization
- **Enhanced coverage reporting** with visual summaries
- **Professional documentation guides** for developers

#### **Testing Infrastructure**

- **Modular test organization** by functionality (not source structure)
- **Comprehensive test coverage** with quality metrics
- **Automated code quality checks** with Aqua.jl
- **Performance and type stability testing**

#### **Developer Experience**

- **Improved error messages** with actionable suggestions
- **Better Unicode support** for mathematical notation
- **Enhanced description management** with intelligent completion
- **Professional project structure** following Julia best practices

### 🔧 Internal Changes

#### **Code Quality**

- **Strict adherence** to Julia style guidelines
- **Comprehensive type annotations** for better performance
- **Memory allocation optimization** for critical paths
- **Extensive documentation** for all public APIs

#### **Testing Standards**

- **Contract-first testing** methodology
- **Unit and integration test separation**
- **Mock and fake implementations** for isolated testing
- **Deterministic and reproducible tests**

#### **Performance**

- **Type stability improvements** throughout the codebase
- **Reduced memory allocations** in hot paths
- **Optimized Unicode operations**
- **Efficient description matching algorithms**

### 📦 Dependencies

#### **New Dependencies**

- `Aqua = "0.8"`: Code quality and consistency checks
- `OrderedCollections = "1"`: Ordered data structures for testing

#### **Updated Compatibility**

- Julia `1.10+` (increased from `1.8+`)
- Updated all package compatibility bounds

### 🏗️ Project Structure

#### **New Directory Organization**

```text
src/
├── Core/ # Fundamental types and utilities
├── Exceptions/ # Enhanced error handling system
├── Unicode/ # Unicode character utilities
├── Descriptions/ # Description management
└── Extensions/ # Extension system

test/
├── suite/ # Modular test suites by functionality
├── extras/ # Example tests and diagnostics
└── src/ # Source-level integration tests

docs/
└── src/ # Modular documentation tutorials
```

#### **Extension System**

```text
ext/
├── CoveragePostprocessing.jl # Coverage analysis
├── DocumenterReference.jl # API documentation
└── TestRunner.jl # Advanced test execution
```

### 🎯 Breaking Changes

See [BREAKINGS.md](BREAKINGS.md) for detailed migration guide.

### 🙏 Acknowledgments

This major release represents a significant investment in code quality, developer experience, and long-term maintainability. The modular architecture provides a solid foundation for future enhancements while maintaining backward compatibility where possible.

---

## [0.17.4] - Previous Release

### 📝 Previous Changes
Expand Down
2 changes: 1 addition & 1 deletion Project.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name = "CTBase"
uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
version = "0.18.0-beta"
version = "0.18.0-beta.1"
authors = ["Olivier Cots <olivier.cots@irit.fr>", "Jean-Baptiste Caillau <caillau@univ-cotedazur.fr>"]

[deps]
Expand Down
1 change: 0 additions & 1 deletion docs/Project.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
[deps]
CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
Coverage = "a2441757-f6aa-5fb2-8edb-039e3f45d037"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
Expand Down
Loading
Loading