Enhance ImGuiTestHarness with dynamic test integration and end-to-end validation
- Updated README.md to reflect the completion of IT-01 and the transition to end-to-end validation phase. - Introduced a new end-to-end test script (scripts/test_harness_e2e.sh) for validating all RPC methods of the ImGuiTestHarness gRPC service. - Implemented dynamic test functionality in ImGuiTestHarnessService for Type, Wait, and Assert methods, utilizing ImGuiTestEngine. - Enhanced error handling and response messages for better clarity during test execution. - Updated existing methods to support dynamic test registration and execution, ensuring robust interaction with the GUI elements.
This commit is contained in:
scawful
229
docs/z3ed/archive/GRPC_TECHNICAL_NOTES.md
Normal file
229
docs/z3ed/archive/GRPC_TECHNICAL_NOTES.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# gRPC Technical Notes
|
||||
|
||||
**Purpose**: Technical reference for gRPC integration issues and solutions
|
||||
**Date**: October 1, 2025
|
||||
**Status**: Reference only - issues resolved
|
||||
|
||||
---
|
||||
|
||||
## Build Configuration (Working)
|
||||
|
||||
**gRPC Version**: v1.62.0
|
||||
**Build Method**: FetchContent (CMake)
|
||||
**C++ Standard**: C++17 (gRPC), C++23 (YAZE)
|
||||
**Compiler**: Clang 18.1.8 (Homebrew)
|
||||
**Platform**: macOS ARM64, SDK 15.0
|
||||
|
||||
### Critical CMake Settings
|
||||
|
||||
```cmake
|
||||
# Force C++17 for gRPC build (avoid std::result_of removal in C++20)
|
||||
set(CMAKE_CXX_STANDARD 17)
|
||||
|
||||
# Suppress Clang 18 template syntax warnings
|
||||
add_compile_options(-Wno-error=missing-template-arg-list-after-template-kw)
|
||||
|
||||
# Prevent system package interference
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_Protobuf TRUE)
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_absl TRUE)
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_gRPC TRUE)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issues Encountered & Resolved
|
||||
|
||||
### Issue 1: Template Syntax Errors (Clang 15+)
|
||||
|
||||
**Error**:
|
||||
```
|
||||
error: a template argument list is expected after a name prefixed by the template keyword
|
||||
[-Wmissing-template-arg-list-after-template-kw]
|
||||
```
|
||||
|
||||
**Versions Affected**: gRPC v1.60.0, v1.62.0, v1.68.0, v1.70.1
|
||||
**Root Cause**: Clang 15+ enforces stricter C++ template syntax
|
||||
**Solution**: Add `-Wno-error=missing-template-arg-list-after-template-kw` compiler flag
|
||||
**Status**: ✅ Resolved - warnings demoted to non-fatal
|
||||
|
||||
### Issue 2: std::result_of Removed (C++20)
|
||||
|
||||
**Error**:
|
||||
```
|
||||
error: no template named 'result_of' in namespace 'std'
|
||||
```
|
||||
|
||||
**Versions Affected**: All gRPC versions when built with C++20+
|
||||
**Root Cause**:
|
||||
- `std::result_of` deprecated in C++17, removed in C++20
|
||||
- YAZE uses C++23, which propagated to gRPC build
|
||||
- gRPC v1.62.0 still uses legacy `std::result_of`
|
||||
|
||||
**Solution**: Force gRPC to build with C++17 standard
|
||||
**Status**: ✅ Resolved - C++17 forced for gRPC, C++23 preserved for YAZE
|
||||
|
||||
### Issue 3: absl::if_constexpr Not Found
|
||||
|
||||
**Error**:
|
||||
```
|
||||
CMake Error: Target "protoc" links to: absl::if_constexpr but the target was not found.
|
||||
```
|
||||
|
||||
**Versions Affected**: gRPC v1.68.0, v1.70.1
|
||||
**Root Cause**: Internal dependency version skew in gRPC
|
||||
**Solution**: Downgrade to gRPC v1.62.0 (stable version)
|
||||
**Status**: ✅ Resolved - v1.62.0 has consistent internal dependencies
|
||||
|
||||
### Issue 4: System Package Interference
|
||||
|
||||
**Error**:
|
||||
```
|
||||
CMake Error: Imported target "protobuf::libprotobuf" includes non-existent path
|
||||
```
|
||||
|
||||
**Root Cause**:
|
||||
- Homebrew-installed protobuf/abseil found by CMake
|
||||
- System versions conflict with gRPC's bundled versions
|
||||
|
||||
**Solution**:
|
||||
```cmake
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_Protobuf TRUE)
|
||||
set(CMAKE_DISABLE_FIND_PACKAGE_absl TRUE)
|
||||
```
|
||||
|
||||
**Status**: ✅ Resolved - system packages ignored during gRPC build
|
||||
|
||||
### Issue 5: Incomplete Type (gRPC v1.60.0)
|
||||
|
||||
**Error**:
|
||||
```
|
||||
error: allocation of incomplete type 'grpc_core::HealthProducer::HealthChecker::HealthStreamEventHandler'
|
||||
```
|
||||
|
||||
**Version Affected**: gRPC v1.60.0 only
|
||||
**Root Cause**: Bug in gRPC v1.60.0 health checking code
|
||||
**Solution**: Upgrade to v1.62.0
|
||||
**Status**: ✅ Resolved - bug fixed in v1.62.0
|
||||
|
||||
---
|
||||
|
||||
## Version Testing Results
|
||||
|
||||
| gRPC Version | C++ Std | Clang 18 | Result | Notes |
|
||||
|--------------|---------|----------|--------|-------|
|
||||
| v1.70.1 | C++23 | ❌ | Failed | `absl::if_constexpr` missing |
|
||||
| v1.68.0 | C++23 | ❌ | Failed | `absl::if_constexpr` missing |
|
||||
| v1.60.0 | C++23 | ❌ | Failed | Incomplete type error |
|
||||
| v1.60.0 | C++17 | ❌ | Failed | Incomplete type persists |
|
||||
| v1.62.0 | C++23 | ❌ | Failed | `std::result_of` removed |
|
||||
| v1.62.0 | C++17 | ✅ | **SUCCESS** | All issues resolved |
|
||||
|
||||
---
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Build Time (First)**: ~20 minutes (gRPC + Protobuf from source)
|
||||
**Build Time (Cached)**: ~5-10 seconds
|
||||
**Binary Size**: +74 MB (ARM64 with gRPC)
|
||||
**RPC Latency**: 2-5ms (Ping test)
|
||||
**Memory Overhead**: ~10 MB (server runtime)
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Build Verification
|
||||
```bash
|
||||
# Clean build
|
||||
rm -rf build-grpc-test
|
||||
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||
|
||||
# Should complete in ~3-4 minutes (configuration)
|
||||
# Look for: "-- Configuring done"
|
||||
|
||||
# Build
|
||||
cmake --build build-grpc-test --target yaze -j$(sysctl -n hw.ncpu)
|
||||
|
||||
# Should complete in ~20 minutes first time
|
||||
# Look for: "Built target yaze"
|
||||
```
|
||||
|
||||
### Runtime Verification
|
||||
```bash
|
||||
# Start server
|
||||
./build-grpc-test/bin/yaze.app/Contents/MacOS/yaze --enable_test_harness &
|
||||
|
||||
# Test Ping
|
||||
grpcurl -plaintext -d '{"message":"test"}' 127.0.0.1:50051 \
|
||||
yaze.test.ImGuiTestHarness/Ping
|
||||
|
||||
# Expected: {"message":"Pong: test", "timestampMs":"...", "yazeVersion":"0.3.2"}
|
||||
```
|
||||
|
||||
### All RPCs
|
||||
```bash
|
||||
# List services
|
||||
grpcurl -plaintext 127.0.0.1:50051 list
|
||||
|
||||
# Test each RPC
|
||||
for rpc in Ping Click Type Wait Assert Screenshot; do
|
||||
echo "Testing $rpc..."
|
||||
grpcurl -plaintext -d '{}' 127.0.0.1:50051 \
|
||||
yaze.test.ImGuiTestHarness/$rpc || echo "Failed"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Future Upgrade Path
|
||||
|
||||
### When to Upgrade gRPC
|
||||
|
||||
Monitor for:
|
||||
- ✅ gRPC v1.70+ reaches LTS status
|
||||
- ✅ Abseil stabilizes `if_constexpr` implementation
|
||||
- ✅ gRPC removes `std::result_of` usage
|
||||
- ✅ Community adoption (3+ months old)
|
||||
|
||||
### Testing New Versions
|
||||
|
||||
```bash
|
||||
# 1. Update cmake/grpc.cmake
|
||||
GIT_TAG v1.XX.0
|
||||
|
||||
# 2. Test with C++17 first
|
||||
set(CMAKE_CXX_STANDARD 17)
|
||||
|
||||
# 3. Try C++20 if C++17 works
|
||||
set(CMAKE_CXX_STANDARD 20)
|
||||
|
||||
# 4. Test all platforms
|
||||
# - macOS ARM64 (Clang 18)
|
||||
# - Ubuntu 22.04 (GCC 11)
|
||||
# - Windows 11 (MSVC 2022)
|
||||
|
||||
# 5. Document any new issues
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known Limitations
|
||||
|
||||
1. **C++23 Incompatibility**: gRPC v1.62.0 not compatible with C++20+
|
||||
2. **Build Time**: First build takes 20 minutes (inevitable with FetchContent)
|
||||
3. **Binary Size**: +74 MB overhead (acceptable for test harness feature)
|
||||
4. **Compiler Warnings**: ~50 template warnings (non-fatal, gRPC issue)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- gRPC Releases: https://github.com/grpc/grpc/releases
|
||||
- gRPC C++ Docs: https://grpc.io/docs/languages/cpp/
|
||||
- Abseil Compatibility: https://abseil.io/about/compatibility
|
||||
- Protobuf Releases: https://github.com/protocolbuffers/protobuf/releases
|
||||
|
||||
---
|
||||
|
||||
**Maintainer Note**: This file documents resolved issues for historical reference.
|
||||
Current working configuration is in `cmake/grpc.cmake`.
|
||||
Reference in New Issue
Block a user