git.zone/tstest
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

BREAKING CHANGE(protocol): Introduce protocol v2 implementation and update build configuration with revised build order, new tspublish files, and enhanced documentation

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-25 19:37:13 +00:00
parent 7d09b39f2b
commit 7b1732abcc
8 changed files with 77 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
readme.plan.md
View File

@@ -13,12 +13,27 @@
- Use Unicode delimiters `⟦TSTEST:META:{}⟧` that won't appear in test names
- Structured JSON metadata format
- Separate protocol blocks for complex data (errors, snapshots)
- Backwards compatible with gradual migration
- Complete replacement of v1 (no backwards compatibility needed)
### Implementation
- Phase 1: Add protocol v2 parser alongside v1
- Phase 2: Generate v2 by default with --legacy flag for v1
- Phase 3: Full migration to v2 in next major version
- Phase 1: Create protocol v2 implementation in ts_tapbundle_protocol
- Phase 2: Replace all v1 code in both tstest and tapbundle with v2
- Phase 3: Delete all v1 parsing and generation code
#### ts_tapbundle_protocol Directory
The protocol v2 implementation will be contained in the `ts_tapbundle_protocol` directory as isomorphic TypeScript code:
- **Isomorphic Design**: All code must work in both browser and Node.js environments
- **No Node.js Imports**: No Node.js-specific modules allowed (no fs, path, child_process, etc.)
- **Protocol Classes**: Contains classes implementing all sides of the protocol:
- `ProtocolEmitter`: For generating protocol v2 messages (used by tapbundle)
- `ProtocolParser`: For parsing protocol v2 messages (used by tstest)
- `ProtocolMessage`: Base classes for different message types
- `ProtocolTypes`: TypeScript interfaces and types for protocol structures
- **Pure TypeScript**: Only browser-compatible APIs and pure TypeScript/JavaScript code
- **Build Integration**:
- Compiled by `pnpm build` (via tsbuild) to `dist_ts_tapbundle_protocol/`
- Build order defined in tspublish.json files
- Imported by ts and ts_tapbundle modules from the compiled dist directory
See `readme.protocol.md` for detailed specification.
@@ -183,10 +198,18 @@ tstest --changed
## Implementation Phases
### Phase 1: Improved Internal Protocol (Priority: Critical) (NEW)
1. Implement Protocol V2 parser in tstest
2. Add protocol version negotiation
3. Update tapbundle to generate V2 format with feature flag
4. Test with real-world test suites containing special characters
1. Create ts_tapbundle_protocol directory with isomorphic protocol v2 implementation
- Implement ProtocolEmitter class for message generation
- Implement ProtocolParser class for message parsing
- Define ProtocolMessage types and interfaces
- Ensure all code is browser and Node.js compatible
- Add tspublish.json to configure build order
2. Update build configuration to compile ts_tapbundle_protocol first
3. Replace TAP parser in tstest with Protocol V2 parser importing from dist_ts_tapbundle_protocol
4. Replace TAP generation in tapbundle with Protocol V2 emitter importing from dist_ts_tapbundle_protocol
5. Delete all v1 TAP parsing code from tstest
6. Delete all v1 TAP generation code from tapbundle
7. Test with real-world test suites containing special characters
### Phase 2: Test Configuration System (Priority: High)
1. Implement tap.settings() API with TypeScript interfaces
@@ -214,10 +237,10 @@ tstest --changed
## Technical Considerations
### API Design Principles
- Maintain backward compatibility
- Clean, modern API design without legacy constraints
- Progressive enhancement approach
- Opt-in features to avoid breaking changes
- Clear migration paths for new features
- Well-documented features and APIs
- Clear, simple interfaces
### Performance Goals
- Minimal overhead for test execution