@git.zone/tstest 1.9.1 → 1.9.3

package/readme.plan.md

@@ -2,6 +2,81 @@
 
 !! FIRST: Reread /home/philkunz/.claude/CLAUDE.md to ensure following all guidelines !!
 
+## Improved Internal Protocol (NEW - Critical)
+
+### Current Issues
+- TAP protocol uses `#` for metadata which conflicts with test descriptions containing `#`
+- Fragile regex parsing that breaks with special characters
+- Limited extensibility for new metadata types
+
+### Proposed Solution: Protocol V2
+- 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
+
+### 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
+
+See `readme.protocol.md` for detailed specification.
+
+## Test Configuration System (NEW)
+
+### Global Test Configuration via 00init.ts
+- **Discovery**: Check for `test/00init.ts` before running tests
+- **Execution**: Import and execute before any test files if found
+- **Purpose**: Define project-wide default test settings
+
+### tap.settings() API
+```typescript
+interface TapSettings {
+  // Timing
+  timeout?: number;              // Default timeout for all tests (ms)
+  slowThreshold?: number;        // Mark tests as slow if they exceed this (ms)
+  
+  // Execution Control
+  bail?: boolean;                // Stop on first test failure
+  retries?: number;              // Number of retries for failed tests
+  retryDelay?: number;           // Delay between retries (ms)
+  
+  // Output Control
+  suppressConsole?: boolean;     // Suppress console output in passing tests
+  verboseErrors?: boolean;       // Show full stack traces
+  showTestDuration?: boolean;    // Show duration for each test
+  
+  // Parallel Execution
+  maxConcurrency?: number;       // Max parallel tests (for .para files)
+  isolateTests?: boolean;        // Run each test in fresh context
+  
+  // Lifecycle Hooks
+  beforeAll?: () => Promise<void> | void;
+  afterAll?: () => Promise<void> | void;
+  beforeEach?: (testName: string) => Promise<void> | void;
+  afterEach?: (testName: string, passed: boolean) => Promise<void> | void;
+  
+  // Environment
+  env?: Record<string, string>;  // Additional environment variables
+  
+  // Features
+  enableSnapshots?: boolean;     // Enable snapshot testing
+  snapshotDirectory?: string;    // Custom snapshot directory
+  updateSnapshots?: boolean;     // Update snapshots instead of comparing
+}
+```
+
+### Settings Inheritance
+- Global (00init.ts) → File level → Test level
+- More specific settings override less specific ones
+- Arrays/objects are merged, primitives are replaced
+
+### Implementation Phases
+1. **Core Infrastructure**: Settings storage and merge logic
+2. **Discovery**: 00init.ts loading mechanism
+3. **Application**: Apply settings to test execution
+4. **Advanced**: Parallel execution and snapshot configuration
+
 ## 1. Enhanced Communication Between tapbundle and tstest
 
 ### 1.1 Real-time Test Progress API
@@ -18,45 +93,9 @@
 
 ## 2. Enhanced toolsArg Functionality
 
-### 2.1 Test Flow Control ✅
-```typescript
-tap.test('conditional test', async (toolsArg) => {
-  const result = await someOperation();
-  
-  // Skip the rest of the test
-  if (!result) {
-    return toolsArg.skip('Precondition not met');
-  }
-  
-  // Conditional skipping
-  await toolsArg.skipIf(condition, 'Reason for skipping');
-  
-  // Mark test as todo
-  await toolsArg.todo('Not implemented yet');
-});
-```
-
-### 2.2 Test Metadata and Configuration ✅
-```typescript
-// Fluent syntax ✅
-tap.tags('slow', 'integration')
-  .priority('high')
-  .timeout(5000)
-  .retry(3)
-  .test('configurable test', async (toolsArg) => {
-    // Test implementation
-  });
-```
-
-### 2.3 Test Data and Context Sharing ✅
+### 2.3 Test Data and Context Sharing (Partial)
 ```typescript
 tap.test('data-driven test', async (toolsArg) => {
-  // Access shared context ✅
-  const sharedData = toolsArg.context.get('sharedData');
-  
-  // Set data for other tests ✅
-  toolsArg.context.set('resultData', computedValue);
-  
   // Parameterized test data (not yet implemented)
   const testData = toolsArg.data<TestInput>();
   expect(processData(testData)).toEqual(expected);
@@ -65,32 +104,7 @@ tap.test('data-driven test', async (toolsArg) => {
 
 ## 3. Nested Tests and Test Suites
 
-### 3.1 Test Grouping with describe() ✅
-```typescript
-tap.describe('User Authentication', () => {
-  tap.beforeEach(async (toolsArg) => {
-    // Setup for each test in this suite
-    await toolsArg.context.set('db', await createTestDatabase());
-  });
-  
-  tap.afterEach(async (toolsArg) => {
-    // Cleanup after each test
-    await toolsArg.context.get('db').cleanup();
-  });
-  
-  tap.test('should login with valid credentials', async (toolsArg) => {
-    // Test implementation
-  });
-  
-  tap.describe('Password Reset', () => {
-    tap.test('should send reset email', async (toolsArg) => {
-      // Nested test
-    });
-  });
-});
-```
-
-### 3.2 Hierarchical Test Organization
+### 3.2 Hierarchical Test Organization (Not yet implemented)
 - Support for multiple levels of nesting
 - Inherited context and configuration from parent suites
 - Aggregated reporting for test suites
@@ -98,15 +112,7 @@ tap.describe('User Authentication', () => {
 
 ## 4. Advanced Test Features
 
-### 4.1 Snapshot Testing
-```typescript
-tap.test('component render', async (toolsArg) => {
-  const output = renderComponent(props);
-  
-  // Compare with stored snapshot
-  await toolsArg.matchSnapshot(output, 'component-output');
-});
-```
+### 4.1 Snapshot Testing ✅ (Basic implementation complete)
 
 ### 4.2 Performance Benchmarking
 ```typescript
@@ -124,30 +130,9 @@ tap.test('performance test', async (toolsArg) => {
 });
 ```
 
-### 4.3 Test Fixtures and Factories ✅
-```typescript
-tap.test('with fixtures', async (toolsArg) => {
-  // Create test fixtures
-  const user = await toolsArg.fixture('user', { name: 'Test User' });
-  const post = await toolsArg.fixture('post', { author: user });
-  
-  // Use factory functions
-  const users = await toolsArg.factory('user').createMany(5);
-});
-```
 
 ## 5. Test Execution Improvements
 
-### 5.1 Parallel Test Execution ✅
-- Run independent tests concurrently ✅
-- Configurable concurrency limits (via file naming convention)
-- Resource pooling for shared resources
-- Proper isolation between parallel tests ✅
-
-Implementation:
-- Tests with `para__<groupNumber>` in filename run in parallel
-- Different groups run sequentially
-- Tests without `para__` run serially
 
 ### 5.2 Watch Mode
 - Automatically re-run tests on file changes
@@ -155,11 +140,8 @@ Implementation:
 - Fast feedback loop for development
 - Integration with IDE/editor plugins
 
-### 5.3 Advanced Test Filtering ✅ (partially)
+### 5.3 Advanced Test Filtering (Partial)
 ```typescript
-// Run tests by tags ✅
-tstest --tags "unit,fast"
-
 // Exclude tests by pattern (not yet implemented)
 tstest --exclude "**/slow/**"
 
@@ -198,50 +180,36 @@ tstest --changed
 - Links to documentation
 - Code examples in error output
 
-### 7.2 Interactive Mode (Needs Detailed Specification)
-- REPL for exploring test failures
-  - Need to define: How to enter interactive mode? When tests fail?
-  - What commands/features should be available in the REPL?
-- Debugging integration  
-  - Node.js inspector protocol integration?
-  - Breakpoint support?
-- Step-through test execution
-  - Pause between tests? 
-  - Step into/over/out functionality?
-- Interactive test data manipulation
-  - Modify test inputs on the fly?
-  - Inspect intermediate values?
-
-### 7.3 ~~VS Code Extension~~ (Scratched)
-- ~~Test explorer integration~~
-- ~~Inline test results~~
-- ~~CodeLens for running individual tests~~
-- ~~Debugging support~~
-
 ## Implementation Phases
 
-### Phase 1: Core Enhancements (Priority: High) ✅
-1. Implement enhanced toolsArg methods (skip, skipIf, timeout, retry) ✅
-2. Add basic test grouping with describe() ✅
-3. Improve error reporting between tapbundle and tstest ✅
+### 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
+
+### Phase 2: Test Configuration System (Priority: High)
+1. Implement tap.settings() API with TypeScript interfaces
+2. Add 00init.ts discovery and loading mechanism
+3. Implement settings inheritance and merge logic
+4. Apply settings to test execution (timeouts, retries, etc.)
 
-### Phase 2: Advanced Features (Priority: Medium)
-1. Implement nested test suites ✅ (basic describe support)
-2. Add snapshot testing ✅
-3. Create test fixture system ✅
-4. Implement parallel test execution ✅
+### Phase 3: Enhanced Communication (Priority: High)
+1. Build on Protocol V2 for richer communication
+2. Implement real-time test progress API
+3. Add structured error reporting with diffs and traces
 
-### Phase 3: Developer Experience (Priority: Medium)
+### Phase 4: Developer Experience (Priority: Medium)
 1. Add watch mode
 2. Implement custom reporters
-3. ~~Create VS Code extension~~ (Scratched)
-4. Add interactive debugging (Needs detailed spec first)
+3. Complete advanced test filtering options
+4. Add performance benchmarking API
 
-### Phase 4: Analytics and Performance (Priority: Low)
+### Phase 5: Analytics and Performance (Priority: Low)
 1. Build test analytics dashboard
-2. Add performance benchmarking
-3. Implement coverage integration
-4. Create trend analysis tools
+2. Implement coverage integration
+3. Create trend analysis tools
+4. Add test impact analysis
 
 ## Technical Considerations
 

package/readme.protocol.md

@@ -0,0 +1,287 @@
+# Improved Internal Protocol Design
+
+## Current Issues with TAP Protocol
+
+1. **Delimiter Conflict**: Using `#` for metadata conflicts with test descriptions containing `#`
+2. **Ambiguous Parsing**: No clear boundary between test name and metadata
+3. **Limited Extensibility**: Adding new metadata requires regex changes
+4. **Mixed Concerns**: Protocol data mixed with human-readable output
+
+## Proposed Internal Protocol v2
+
+### Design Principles
+
+1. **Clear Separation**: Protocol data must be unambiguously separated from user content
+2. **Extensibility**: Easy to add new metadata without breaking parsers
+3. **Backwards Compatible**: Can coexist with standard TAP for gradual migration
+4. **Machine Readable**: Structured format for reliable parsing
+5. **Human Friendly**: Still readable in raw form
+
+### Protocol Options
+
+#### Option 1: Special Delimiters
+```
+ok 1 - test description ::TSTEST:: {"time":123,"retry":0}
+not ok 2 - another test ::TSTEST:: {"time":45,"error":"timeout"}
+ok 3 - skipped test ::TSTEST:: {"time":0,"skip":"not ready"}
+```
+
+**Pros**: 
+- Simple to implement
+- Backwards compatible with TAP parsers (they ignore the suffix)
+- Easy to parse with split()
+
+**Cons**: 
+- Still could conflict if test name contains `::TSTEST::`
+- Not standard TAP
+
+#### Option 2: Separate Metadata Lines
+```
+ok 1 - test description
+::METADATA:: {"test":1,"time":123,"retry":0}
+not ok 2 - another test  
+::METADATA:: {"test":2,"time":45,"error":"timeout"}
+```
+
+**Pros**:
+- Complete separation of concerns
+- No chance of conflicts
+- Can include arbitrary metadata
+
+**Cons**:
+- Requires correlation between lines
+- More complex parsing
+
+#### Option 3: YAML Blocks (TAP 13 Compatible)
+```
+ok 1 - test description
+  ---
+  time: 123
+  retry: 0
+  ...
+not ok 2 - another test
+  ---
+  time: 45
+  error: timeout
+  stack: |
+    Error: timeout
+      at Test.run (test.js:10:5)
+  ...
+```
+
+**Pros**:
+- Standard TAP 13 feature
+- Structured data format
+- Human readable
+- Extensible
+
+**Cons**:
+- More verbose
+- YAML parsing overhead
+
+#### Option 4: Binary Protocol Markers (Recommended)
+```
+ok 1 - test description
+␛[TSTEST:eyJ0aW1lIjoxMjMsInJldHJ5IjowfQ==]␛
+not ok 2 - another test
+␛[TSTEST:eyJ0aW1lIjo0NSwiZXJyb3IiOiJ0aW1lb3V0In0=]␛
+```
+
+Using ASCII escape character (␛ = \x1B) with base64 encoded JSON.
+
+**Pros**:
+- Zero chance of accidental conflicts
+- Compact
+- Fast to parse
+- Invisible in most terminals
+
+**Cons**:
+- Not human readable in raw form
+- Requires base64 encoding/decoding
+
+### Recommended Implementation: Hybrid Approach
+
+Use multiple strategies based on context:
+
+1. **For timing and basic metadata**: Use structured delimiters
+   ```
+   ok 1 - test name ⟦time:123,retry:0⟧
+   ```
+
+2. **For complex data (errors, snapshots)**: Use separate protocol lines
+   ```
+   ok 1 - test failed
+   ⟦TSTEST:ERROR⟧
+   {"message":"Assertion failed","stack":"...","diff":"..."}
+   ⟦/TSTEST:ERROR⟧
+   ```
+
+3. **For human-readable output**: Keep standard TAP comments
+   ```
+   # Test suite: User Authentication
+   ok 1 - should login
+   ```
+
+### Implementation Plan
+
+#### Phase 1: Parser Enhancement
+1. Add new protocol parser alongside existing TAP parser
+2. Support both old and new formats during transition
+3. Add protocol version negotiation
+
+#### Phase 2: Metadata Structure
+```typescript
+interface TestMetadata {
+  // Timing
+  time: number;           // milliseconds
+  startTime?: number;     // Unix timestamp
+  endTime?: number;       // Unix timestamp
+  
+  // Status
+  skip?: string;          // skip reason
+  todo?: string;          // todo reason
+  retry?: number;         // retry attempt
+  maxRetries?: number;    // max retries allowed
+  
+  // Error details
+  error?: {
+    message: string;
+    stack?: string;
+    diff?: string;
+    actual?: any;
+    expected?: any;
+  };
+  
+  // Test context
+  file?: string;          // source file
+  line?: number;          // line number
+  column?: number;        // column number
+  
+  // Custom data
+  tags?: string[];        // test tags
+  custom?: Record<string, any>;
+}
+```
+
+#### Phase 3: Protocol Messages
+
+##### Success Message
+```
+ok 1 - user authentication works
+⟦TSTEST:META:{"time":123,"tags":["auth","unit"]}⟧
+```
+
+##### Failure Message
+```
+not ok 2 - login fails with invalid password
+⟦TSTEST:META:{"time":45,"retry":1,"maxRetries":3}⟧
+⟦TSTEST:ERROR⟧
+{
+  "message": "Expected 401 but got 500",
+  "stack": "Error: Expected 401 but got 500\n    at Test.run (auth.test.ts:25:10)",
+  "actual": 500,
+  "expected": 401
+}
+⟦/TSTEST:ERROR⟧
+```
+
+##### Skip Message
+```
+ok 3 - database integration test ⟦TSTEST:SKIP:No database connection⟧
+```
+
+##### Snapshot Communication
+```
+⟦TSTEST:SNAPSHOT:user-profile⟧
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "roles": ["user", "admin"]
+}
+⟦/TSTEST:SNAPSHOT⟧
+```
+
+### Migration Strategy
+
+1. **Version Detection**: First line indicates protocol version
+   ```
+   ⟦TSTEST:PROTOCOL:2.0⟧
+   TAP version 13
+   ```
+
+2. **Gradual Rollout**:
+   - v1.10: Add protocol v2 parser, keep v1 generator
+   - v1.11: Generate v2 by default, v1 with --legacy flag  
+   - v2.0: Remove v1 support
+
+3. **Feature Flags**:
+   ```typescript
+   tap.settings({
+     protocol: 'v2',        // or 'v1', 'auto'
+     protocolFeatures: {
+       structuredErrors: true,
+       enhancedTiming: true,
+       binaryMarkers: false
+     }
+   });
+   ```
+
+### Benefits of New Protocol
+
+1. **Reliability**: No more regex fragility or description conflicts
+2. **Performance**: Faster parsing with clear boundaries
+3. **Extensibility**: Easy to add new metadata fields
+4. **Debugging**: Rich error information with stack traces and diffs
+5. **Integration**: Better IDE and CI/CD tool integration
+6. **Forward Compatible**: Room for future enhancements
+
+### Example Parser Implementation
+
+```typescript
+class ProtocolV2Parser {
+  private readonly MARKER_START = '⟦TSTEST:';
+  private readonly MARKER_END = '⟧';
+  
+  parseMetadata(line: string): TestMetadata | null {
+    const start = line.lastIndexOf(this.MARKER_START);
+    if (start === -1) return null;
+    
+    const end = line.indexOf(this.MARKER_END, start);
+    if (end === -1) return null;
+    
+    const content = line.substring(start + this.MARKER_START.length, end);
+    const [type, data] = content.split(':', 2);
+    
+    switch (type) {
+      case 'META':
+        return JSON.parse(data);
+      case 'SKIP':
+        return { skip: data };
+      case 'TODO':
+        return { todo: data };
+      default:
+        return null;
+    }
+  }
+  
+  parseTestLine(line: string): ParsedTest {
+    // First extract any metadata
+    const metadata = this.parseMetadata(line);
+    
+    // Then parse the TAP part (without metadata)
+    const cleanLine = this.removeMetadata(line);
+    const tapResult = this.parseTAP(cleanLine);
+    
+    return { ...tapResult, metadata };
+  }
+}
+```
+
+### Next Steps
+
+1. Implement proof of concept with basic metadata support
+2. Test with real-world test suites for edge cases
+3. Benchmark parsing performance
+4. Get feedback from users
+5. Finalize protocol specification
+6. Implement in both tapbundle and tstest

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tstest',
-  version: '1.9.1',
+  version: '1.9.3',
   description: 'a test utility to run tests that match test/**/*.ts'
 }

package/ts/tstest.classes.tap.parser.ts

@@ -16,7 +16,7 @@ export class TapParser {
   expectedTests: number;
   receivedTests: number;
 
-  testStatusRegex = /(ok|not\sok)\s([0-9]+)\s-\s(.*)(\s#\s(.*))?$/;
+  testStatusRegex = /(ok|not\sok)\s([0-9]+)\s-\s(.*?)(\s#\s(.*))?$/;
   activeTapTestResult: TapTestResult;
   collectingErrorDetails: boolean = false;
   currentTestError: string[] = [];
@@ -77,7 +77,7 @@ export class TapParser {
           return false;
         })();
 
-        const testSubject = regexResult[3];
+        const testSubject = regexResult[3].trim();
         const testMetadata = regexResult[5]; // This will be either "time=XXXms" or "SKIP reason" or "TODO reason"
         
         let testDuration = 0;

package/ts/tstest.logging.ts

@@ -153,8 +153,16 @@ export class TsTestLogger {
     
     // Only set up test log file if --logfile option is specified
     if (this.options.logFile) {
-      const baseFilename = path.basename(filename, '.ts');
-      this.currentTestLogFile = path.join('.nogit', 'testlogs', `${baseFilename}.log`);
+      // Create a safe filename that preserves directory structure
+      // Convert relative path to a flat filename by replacing separators with __
+      const relativeFilename = path.relative(process.cwd(), filename);
+      const safeFilename = relativeFilename
+        .replace(/\\/g, '/') // Normalize Windows paths
+        .replace(/\//g, '__') // Replace path separators with double underscores
+        .replace(/\.ts$/, '') // Remove .ts extension
+        .replace(/^\.\.__|^\.__|^__/, ''); // Clean up leading separators from relative paths
+      
+      this.currentTestLogFile = path.join('.nogit', 'testlogs', `${safeFilename}.log`);
       
       // Ensure the directory exists
       const logDir = path.dirname(this.currentTestLogFile);