# @git.zone/tsrepo/tapbundle_protocol

> 📡 Enhanced TAP Protocol V2 implementation for structured test communication

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Installation

```bash
# tapbundle_protocol is part of @git.zone/tsrepo
pnpm add -D @git.zone/tsrepo
```

This is the former `@git.zone/tstest/tapbundle_protocol` of tstest 8.0.0, unchanged apart from its import path; `@git.zone/tstest/tapbundle_protocol` now re-exports this module.

## Overview

`@git.zone/tsrepo/tapbundle_protocol` implements Protocol V2, an enhanced version of the Test Anything Protocol (TAP) with support for structured metadata, real-time events, error diffs, and isomorphic operation. This protocol enables rich communication between test runners and test consumers while maintaining backward compatibility with standard TAP parsers. [protocol.md](./protocol.md) records why the protocol looks the way it does and which alternatives were considered.

## Key Features

- 📋 **TAP v13 Compliant** - Fully compatible with standard TAP consumers
- 🎯 **Enhanced Metadata** - Timing, tags, errors, diffs, and custom data
- 🔄 **Real-time Events** - Live test execution updates
- 🔍 **Structured Errors** - JSON error blocks with stack traces and diffs
- 📸 **Snapshot Support** - Built-in snapshot testing protocol
- 🌐 **Isomorphic** - Works in Node.js, Chromium and Bun
- 🏷️ **Protocol Markers** - Structured data using Unicode delimiters

## Protocol V2 Format

### Protocol Markers

Protocol V2 uses special Unicode markers to embed structured data within TAP output:

- `⟦TSTEST:` - Start marker
- `⟧` - End marker

These markers allow structured data to coexist with standard TAP without breaking compatibility.

### Example Output

```tap
⟦TSTEST:PROTOCOL:2.0.0⟧
TAP version 13
1..3
ok 1 - should add numbers ⟦TSTEST:time:42⟧
not ok 2 - should validate input
⟦TSTEST:META:{"time":156,"error":{"message":"Expected 5 to equal 6"},"file":"test.ts","line":42}⟧
⟦TSTEST:ERROR⟧
{
  "testNumber": 2,
  "error": {
    "message": "Expected 5 to equal 6"
  }
}
⟦TSTEST:/ERROR⟧
ok 3 - should handle edge cases # SKIP not implemented ⟦TSTEST:SKIP:not implemented⟧
```

`emitTest()` writes simple metadata (`time`, `retry`, or a `skip`/`todo` reason) inline on the test line. As soon as the metadata holds an `error`, `custom` data, `tags`, a `file` or a `line`, it writes the whole metadata (without `skip`/`todo`) as a `⟦TSTEST:META:…⟧` line after the test line, followed by an `ERROR` block when there is an error. `ProtocolParser.parseLine()` reads metadata from the test line only: it returns no message for a `META` line of its own.

## API Reference

### ProtocolEmitter

Generates Protocol V2 messages. Used by tapbundle (`@git.zone/tsrepo/tapbundle`) to emit test results.

#### `emitProtocolHeader()`

Emit the protocol version header.

```typescript
import { ProtocolEmitter } from '@git.zone/tsrepo/tapbundle_protocol';

const emitter = new ProtocolEmitter();
console.log(emitter.emitProtocolHeader());
// Output: ⟦TSTEST:PROTOCOL:2.0.0⟧
```

#### `emitTapVersion(version?)`

Emit TAP version line.

```typescript
console.log(emitter.emitTapVersion(13));
// Output: TAP version 13
```

#### `emitPlan(plan)`

Emit test plan.

```typescript
console.log(emitter.emitPlan({ start: 1, end: 5 }));
// Output: 1..5

console.log(emitter.emitPlan({ start: 1, end: 0, skipAll: 'Not ready' }));
// Output: 1..0 # Skipped: Not ready
```

#### `emitTest(result)`

Emit a test result with optional metadata.

```typescript
const lines = emitter.emitTest({
  ok: true,
  testNumber: 1,
  description: 'should work correctly',
  metadata: {
    time: 45,
    tags: ['unit', 'fast']
  }
});

lines.forEach(line => console.log(line));
// Output (tags make the metadata complex, so it moves to a META line):
// ok 1 - should work correctly
// ⟦TSTEST:META:{"time":45,"tags":["unit","fast"]}⟧

const simple = emitter.emitTest({ ok: true, testNumber: 2, description: 'is fast', metadata: { time: 12 } });
// simple: ['ok 2 - is fast ⟦TSTEST:time:12⟧']
```

#### `emitComment(comment)`

Emit a comment line.

```typescript
console.log(emitter.emitComment('Setup complete'));
// Output: # Setup complete
```

#### `emitBailout(reason)`

Emit a bailout (abort all tests).

```typescript
console.log(emitter.emitBailout('Database connection failed'));
// Output: Bail out! Database connection failed
```

#### `emitError(error)`

Emit a structured error block.

```typescript
const lines = emitter.emitError({
  testNumber: 2,
  error: {
    message: 'Expected 5 to equal 6',
    actual: 5,
    expected: 6
  }
});

lines.forEach(line => console.log(line));
// Output:
// ⟦TSTEST:ERROR⟧
// {
//   "testNumber": 2,
//   "error": {
//     "message": "Expected 5 to equal 6",
//     "actual": 5,
//     "expected": 6
//   }
// }
// ⟦TSTEST:/ERROR⟧
```

#### `emitEvent(event)`

Emit a real-time test event.

```typescript
console.log(emitter.emitEvent({
  eventType: 'test:started',
  timestamp: Date.now(),
  data: {
    testNumber: 1,
    description: 'should work'
  }
}));
// Output: ⟦TSTEST:EVENT:{"eventType":"test:started",...}⟧
```

#### `emitSnapshot(snapshot)`

Emit snapshot data.

```typescript
const lines = emitter.emitSnapshot({
  name: 'user-data',
  content: { name: 'Alice', age: 30 },
  format: 'json'
});

lines.forEach(line => console.log(line));
// Output:
// ⟦TSTEST:SNAPSHOT:user-data⟧
// {
//   "name": "Alice",
//   "age": 30
// }
// ⟦TSTEST:/SNAPSHOT⟧
```

### ProtocolParser

Parses Protocol V2 messages. Used by `tsrepo test` to consume test results.

#### `parseLine(line)`

Parse a single line and return protocol messages.

```typescript
import { ProtocolParser } from '@git.zone/tsrepo/tapbundle_protocol';

const parser = new ProtocolParser();

const messages = parser.parseLine('ok 1 - test passed ⟦TSTEST:time:42⟧');
console.log(messages);
// Output:
// [{
//   type: 'test',
//   content: {
//     ok: true,
//     testNumber: 1,
//     description: 'test passed',
//     metadata: { time: 42 }
//   }
// }]
```

#### Message Types

The parser returns different message types:

```typescript
interface IProtocolMessage {
  type: 'test' | 'plan' | 'comment' | 'version' | 'bailout' | 'protocol' | 'snapshot' | 'error' | 'event';
  content: any;
}
```

**Examples:**

```typescript
// Test result
{
  type: 'test',
  content: {
    ok: true,
    testNumber: 1,
    description: 'test name',
    metadata: { ... }
  }
}

// Plan
{
  type: 'plan',
  content: {
    start: 1,
    end: 5
  }
}

// Event
{
  type: 'event',
  content: {
    eventType: 'test:started',
    timestamp: 1234567890,
    data: { ... }
  }
}

// Error
{
  type: 'error',
  content: {
    testNumber: 2,
    error: {
      message: '...',
      stack: '...',
      diff: '...'
    }
  }
}
```

#### `getProtocolVersion()`

Get the detected protocol version.

```typescript
const version = parser.getProtocolVersion();
console.log(version); // "2.0.0" or null
```

## TypeScript Types

### ITestResult

```typescript
interface ITestResult {
  ok: boolean;
  testNumber: number;
  description: string;
  directive?: {
    type: 'skip' | 'todo';
    reason?: string;
  };
  metadata?: ITestMetadata;
}
```

### ITestMetadata

```typescript
interface ITestMetadata {
  // Timing
  time?: number;              // Test duration in milliseconds
  startTime?: number;         // Unix timestamp
  endTime?: number;           // Unix timestamp

  // Status
  skip?: string;              // Skip reason
  todo?: string;              // Todo reason
  retry?: number;             // Current retry attempt
  maxRetries?: number;        // Max retries allowed

  // Error details
  error?: {
    message: string;
    stack?: string;
    diff?: string;
    actual?: any;
    expected?: any;
    code?: string;
  };

  // Test context
  file?: string;              // Source file path
  line?: number;              // Line number
  column?: number;            // Column number

  // Custom data
  tags?: string[];            // Test tags
  custom?: Record<string, any>;
}
```

### ITestEvent

```typescript
interface ITestEvent {
  eventType: EventType;
  timestamp: number;
  data: {
    testNumber?: number;
    description?: string;
    suiteName?: string;
    hookName?: string;
    progress?: number;        // 0-100
    duration?: number;
    error?: IEnhancedError;
    [key: string]: any;
  };
}

type EventType =
  | 'test:queued'
  | 'test:started'
  | 'test:progress'
  | 'test:completed'
  | 'suite:started'
  | 'suite:completed'
  | 'hook:started'
  | 'hook:completed'
  | 'assertion:failed';
```

### IEnhancedError

```typescript
interface IEnhancedError {
  message: string;
  stack?: string;
  diff?: IDiffResult;
  actual?: any;
  expected?: any;
  code?: string;
  type?: 'assertion' | 'timeout' | 'uncaught' | 'syntax' | 'runtime';
}
```

### IDiffResult

```typescript
interface IDiffResult {
  type: 'string' | 'object' | 'array' | 'primitive';
  changes: IDiffChange[];
  context?: number;           // Lines of context
}

interface IDiffChange {
  type: 'add' | 'remove' | 'modify';
  path?: string[];            // For object/array diffs
  oldValue?: any;
  newValue?: any;
  line?: number;              // For string diffs
  content?: string;
}
```

## Protocol Constants

```typescript
import { PROTOCOL_MARKERS, PROTOCOL_VERSION } from '@git.zone/tsrepo/tapbundle_protocol';

console.log(PROTOCOL_VERSION);         // "2.0.0"
console.log(PROTOCOL_MARKERS.START);   // "⟦TSTEST:"
console.log(PROTOCOL_MARKERS.END);     // "⟧"
```

### Available Markers

```typescript
const PROTOCOL_MARKERS = {
  START: '⟦TSTEST:',
  END: '⟧',
  META_PREFIX: 'META:',
  ERROR_PREFIX: 'ERROR',
  ERROR_END: '/ERROR',
  SNAPSHOT_PREFIX: 'SNAPSHOT:',
  SNAPSHOT_END: '/SNAPSHOT',
  PROTOCOL_PREFIX: 'PROTOCOL:',
  SKIP_PREFIX: 'SKIP:',
  TODO_PREFIX: 'TODO:',
  EVENT_PREFIX: 'EVENT:',
};
```

## Usage Patterns

### Creating a Custom Test Runner

```typescript
import { ProtocolEmitter } from '@git.zone/tsrepo/tapbundle_protocol';

const emitter = new ProtocolEmitter();

// Emit protocol header
console.log(emitter.emitProtocolHeader());
console.log(emitter.emitTapVersion(13));

// Emit plan
console.log(emitter.emitPlan({ start: 1, end: 2 }));

// Run test 1
console.log(emitter.emitEvent({
  eventType: 'test:started',
  timestamp: Date.now(),
  data: { testNumber: 1 }
}));

const result1 = emitter.emitTest({
  ok: true,
  testNumber: 1,
  description: 'first test',
  metadata: { time: 45 }
});
result1.forEach(line => console.log(line));

// Run test 2
const result2 = emitter.emitTest({
  ok: false,
  testNumber: 2,
  description: 'second test',
  metadata: {
    time: 120,
    error: {
      message: 'Assertion failed',
      actual: 5,
      expected: 6
    }
  }
});
result2.forEach(line => console.log(line));
```

### Parsing Test Output

```typescript
import { ProtocolParser } from '@git.zone/tsrepo/tapbundle_protocol';
import * as readline from 'readline';

const parser = new ProtocolParser();

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

rl.on('line', (line) => {
  const messages = parser.parseLine(line);

  messages.forEach(message => {
    switch (message.type) {
      case 'test':
        console.log(`Test ${message.content.testNumber}: ${message.content.ok ? 'PASS' : 'FAIL'}`);
        break;
      case 'event':
        console.log(`Event: ${message.content.eventType}`);
        break;
      case 'error':
        console.error(`Error: ${message.content.error.message}`);
        break;
    }
  });
});
```

### Building Test Dashboards

Real-time events enable building live test dashboards:

```typescript
const parser = new ProtocolParser();

parser.parseLine(line).forEach(message => {
  if (message.type === 'event') {
    const event = message.content;

    switch (event.eventType) {
      case 'test:started':
        updateUI({ status: 'running', test: event.data.description });
        break;
      case 'test:completed':
        updateUI({ status: 'done', duration: event.data.duration });
        break;
      case 'suite:started':
        createSuiteCard(event.data.suiteName);
        break;
    }
  }
});
```

## Backward Compatibility

Protocol V2 is fully backward compatible with standard TAP parsers:

- Protocol markers use Unicode delimiters that do not collide with TAP syntax
- Standard TAP output (ok/not ok, plan, comments) works everywhere
- Enhanced features gracefully degrade in standard TAP consumers

**Standard TAP View:**
```tap
TAP version 13
1..3
ok 1 - should add numbers
not ok 2 - should validate input
ok 3 - should handle edge cases # SKIP not implemented
```

**Protocol V2 View (same output):**
```tap
⟦TSTEST:PROTOCOL:2.0.0⟧
TAP version 13
1..3
ok 1 - should add numbers ⟦TSTEST:time:42⟧
not ok 2 - should validate input ⟦TSTEST:time:156⟧
ok 3 - should handle edge cases # SKIP not implemented ⟦TSTEST:SKIP:not implemented⟧
```

A consumer that does not know the markers reads an inline marker as part of the test description and a marker line as an unknown line.

## Isomorphic Design

This module works in every runtime `tsrepo test` supports:

- ✅ Node.js
- ✅ Chromium (via tapbundle)
- ✅ Bun

It imports nothing and uses no runtime-specific API. Deno is unsupported and untested.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license.md) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
