v2.8.1

changelog.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2025-11-17 - 2.8.1 - fix(config)
+Remove Bun config file and set deno.json useDefineForClassFields to false for compatibility
+
+- Removed bunfig.toml (Bun-specific TypeScript decorator configuration) — stops shipping a project-local Bun transpiler config.
+- Updated deno.json: set compilerOptions.useDefineForClassFields = false to keep legacy class field semantics and avoid runtime/emit incompatibilities in Deno.
+
+## 2025-11-17 - 2.8.0 - feat(runtime-adapters)
+Enable TypeScript decorator support for Deno and Bun runtimes and add decorator tests
+
+- Add bunfig.toml to enable experimentalDecorators for Bun runtime
+- Add deno.json to enable experimentalDecorators and set target/lib for Deno
+- Update Bun runtime adapter to note bunfig.toml discovery so Bun runs with decorator support
+- Update Deno runtime adapter to auto-detect deno.json / deno.jsonc and pass configPath in default options
+- Add integration tests for decorators (test/decorator.all.ts) to verify decorator support across runtimes
+
+## 2025-10-26 - 2.7.0 - feat(tapbundle_protocol)
+Add package export for tapbundle_protocol to expose protocol utilities
+
+- Add './tapbundle_protocol' export in package.json pointing to './dist_ts_tapbundle_protocol/index.js'.
+- Allows consumers to import protocol utilities (ProtocolEmitter, ProtocolParser, types) via '@git.zone/tstest/tapbundle_protocol'.
+- Non-breaking: only extends package exports surface.
+
+## 2025-10-17 - 2.6.2 - fix(@push.rocks/smartrequest)
+Bump @push.rocks/smartrequest from ^4.3.1 to ^4.3.2
+
+- Update dependency @push.rocks/smartrequest from ^4.3.1 to ^4.3.2
+
 ## 2025-10-17 - 2.6.1 - fix(runtime-adapters)
 Silence shell version checks for Bun and Deno; add local Claude settings
 

deno.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "target": "ES2022"
+  },
+  "nodeModulesDir": true,
+  "version": "2.8.1"
+}

package.json

@@ -1,12 +1,13 @@
 {
   "name": "@git.zone/tstest",
-  "version": "2.6.1",
+  "version": "2.8.1",
   "private": false,
   "description": "a test utility to run tests that match test/**/*.ts",
   "exports": {
     ".": "./dist_ts/index.js",
     "./tapbundle": "./dist_ts_tapbundle/index.js",
-    "./tapbundle_node": "./dist_ts_tapbundle_node/index.js"
+    "./tapbundle_node": "./dist_ts_tapbundle_node/index.js",
+    "./tapbundle_protocol": "./dist_ts_tapbundle_protocol/index.js"
   },
   "type": "module",
   "author": "Lossless GmbH",
@@ -46,7 +47,7 @@
     "@push.rocks/smartnetwork": "^4.4.0",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartrequest": "^4.3.1",
+    "@push.rocks/smartrequest": "^4.3.2",
     "@push.rocks/smarts3": "^2.2.6",
     "@push.rocks/smartshell": "^3.3.0",
     "@push.rocks/smarttime": "^4.1.1",

pnpm-lock.yaml

@@ -63,8 +63,8 @@ importers:
         specifier: ^4.2.3
         version: 4.2.3
       '@push.rocks/smartrequest':
-        specifier: ^4.3.1
-        version: 4.3.1
+        specifier: ^4.3.2
+        version: 4.3.2
       '@push.rocks/smarts3':
         specifier: ^2.2.6
         version: 2.2.6
@@ -1047,8 +1047,8 @@ packages:
   '@push.rocks/smartrequest@2.1.0':
     resolution: {integrity: sha512-3eHLTRInHA+u+W98TqJwgTES7rRimBAsJC4JxVNQC3UUezmblAhM5/TIQsEBQTsbjAY8SeQKy6NHzW6iTiaD8w==}
 
-  '@push.rocks/smartrequest@4.3.1':
-    resolution: {integrity: sha512-H5FQSfFEbSJCHpE2A+SasQQcxM5FlxhHIUEzhUsSLjtlCTEu9T7Xb1WzVLFYvdWfyP5VIrg+XM4AMOols8cG+Q==}
+  '@push.rocks/smartrequest@4.3.2':
+    resolution: {integrity: sha512-Alms3xnC9gpXg8XOgsczwJxnXEjAEf6SDUk0/Ykw9OJJVkZIstWkoytGwJS/hByx70WtPENvq30zBqxI1Gl9rQ==}
 
   '@push.rocks/smartrouter@1.3.3':
     resolution: {integrity: sha512-1+xZEnWlhzqLWAaJ1zFNhQ0zgbfCWQl1DBT72LygLxTs+P0K8AwJKgqo/IX6CT55kGCFnPAZIYSbVJlGsgrB0w==}
@@ -3996,7 +3996,7 @@ snapshots:
       '@push.rocks/smartopen': 2.0.0
       '@push.rocks/smartpath': 6.0.0
       '@push.rocks/smartpromise': 4.2.3
-      '@push.rocks/smartrequest': 4.3.1
+      '@push.rocks/smartrequest': 4.3.2
       '@push.rocks/smartrx': 3.0.10
       '@push.rocks/smartsitemap': 2.0.3
       '@push.rocks/smartstream': 3.2.5
@@ -5203,7 +5203,7 @@ snapshots:
       '@push.rocks/smartlog': 3.1.10
       '@push.rocks/smartnpm': 2.0.6
       '@push.rocks/smartpath': 6.0.0
-      '@push.rocks/smartrequest': 4.3.1
+      '@push.rocks/smartrequest': 4.3.2
       '@push.rocks/smartshell': 3.3.0
     transitivePeerDependencies:
       - aws-crt
@@ -5511,7 +5511,7 @@ snapshots:
       '@push.rocks/smartfile': 11.2.7
       '@push.rocks/smartpath': 6.0.0
       '@push.rocks/smartpromise': 4.2.3
-      '@push.rocks/smartrequest': 4.3.1
+      '@push.rocks/smartrequest': 4.3.2
       '@push.rocks/smartrx': 3.0.10
       '@push.rocks/smartstream': 3.2.5
       '@push.rocks/smartunique': 3.0.9
@@ -5693,7 +5693,7 @@ snapshots:
       '@push.rocks/smartmime': 2.0.4
       '@push.rocks/smartpath': 6.0.0
       '@push.rocks/smartpromise': 4.2.3
-      '@push.rocks/smartrequest': 4.3.1
+      '@push.rocks/smartrequest': 4.3.2
       '@push.rocks/smartstream': 3.2.5
       '@types/fs-extra': 11.0.4
       '@types/js-yaml': 4.0.9
@@ -5820,7 +5820,7 @@ snapshots:
       '@push.rocks/smartfile': 11.2.7
       '@push.rocks/smartpath': 6.0.0
       '@push.rocks/smartpromise': 4.2.3
-      '@push.rocks/smartrequest': 4.3.1
+      '@push.rocks/smartrequest': 4.3.2
       '@push.rocks/smarttime': 4.1.1
       '@push.rocks/smartversion': 3.0.5
       package-json: 8.1.1
@@ -5902,7 +5902,7 @@ snapshots:
       agentkeepalive: 4.6.0
       form-data: 4.0.4
 
-  '@push.rocks/smartrequest@4.3.1':
+  '@push.rocks/smartrequest@4.3.2':
     dependencies:
       '@push.rocks/smartenv': 5.0.13
       '@push.rocks/smartpath': 6.0.0

readme.md

@@ -319,6 +319,129 @@ tstest provides multiple exports for different use cases:
 - `@git.zone/tstest` - Main CLI and test runner functionality
 - `@git.zone/tstest/tapbundle` - Browser-compatible test framework
 - `@git.zone/tstest/tapbundle_node` - Node.js-specific test utilities
+- `@git.zone/tstest/tapbundle_protocol` - Protocol V2 emitter and parser for TAP extensions
+
+## tapbundle Protocol V2
+
+tstest includes an enhanced TAP protocol (Protocol V2) that extends standard TAP 13 with additional metadata while maintaining backwards compatibility.
+
+### Overview
+
+Protocol V2 adds structured metadata to TAP output using Unicode markers (`⟦TSTEST:...⟧`) that standard TAP parsers safely ignore. This allows for:
+
+- **Timing information** - Test execution duration in milliseconds
+- **Structured errors** - Stack traces, diffs, and detailed error data
+- **Test events** - Real-time progress and lifecycle events
+- **Snapshots** - Snapshot testing data exchange
+- **Custom metadata** - Tags, retry counts, file locations
+
+### Using the Protocol
+
+```typescript
+import {
+  ProtocolEmitter,
+  ProtocolParser,
+  PROTOCOL_MARKERS,
+  PROTOCOL_VERSION
+} from '@git.zone/tstest/tapbundle_protocol';
+
+// Create an emitter
+const emitter = new ProtocolEmitter();
+
+// Emit protocol header
+console.log(emitter.emitProtocolHeader());
+// Output: ⟦TSTEST:PROTOCOL:2.0.0⟧
+
+// Emit TAP version
+console.log(emitter.emitTapVersion(13));
+// Output: TAP version 13
+
+// Emit a test result with metadata
+const testResult = {
+  ok: true,
+  testNumber: 1,
+  description: 'user authentication works',
+  metadata: {
+    time: 123,
+    tags: ['auth', 'unit']
+  }
+};
+console.log(emitter.emitTest(testResult).join('\n'));
+// Output: ok 1 - user authentication works ⟦TSTEST:time:123⟧
+//         ⟦TSTEST:META:{"tags":["auth","unit"]}⟧
+```
+
+### Protocol Markers
+
+```typescript
+PROTOCOL_MARKERS = {
+  START: '⟦TSTEST:',
+  END: '⟧',
+  META_PREFIX: 'META:',
+  ERROR_PREFIX: 'ERROR',
+  SNAPSHOT_PREFIX: 'SNAPSHOT:',
+  SKIP_PREFIX: 'SKIP:',
+  TODO_PREFIX: 'TODO:',
+  EVENT_PREFIX: 'EVENT:'
+}
+```
+
+### Use Cases
+
+#### Creating Custom Test Runners
+
+```typescript
+import { ProtocolEmitter } from '@git.zone/tstest/tapbundle_protocol';
+
+const emitter = new ProtocolEmitter();
+
+// Emit header and version
+console.log(emitter.emitProtocolHeader());
+console.log(emitter.emitTapVersion(13));
+console.log(emitter.emitPlan({ start: 1, end: 2 }));
+
+// Run your tests and emit results
+const startTime = Date.now();
+// ... run test ...
+const duration = Date.now() - startTime;
+
+console.log(emitter.emitTest({
+  ok: true,
+  testNumber: 1,
+  description: 'my custom test',
+  metadata: { time: duration }
+}).join('\n'));
+```
+
+#### Parsing tapbundle Output
+
+```typescript
+import { ProtocolParser } from '@git.zone/tstest/tapbundle_protocol';
+
+const parser = new ProtocolParser();
+
+// Parse TAP output line by line
+parser.parseLine('⟦TSTEST:PROTOCOL:2.0.0⟧');
+parser.parseLine('TAP version 13');
+parser.parseLine('1..1');
+parser.parseLine('ok 1 - test name ⟦TSTEST:time:123⟧');
+
+// Get parsed results
+const results = parser.getResults();
+console.log(results);
+```
+
+### Backwards Compatibility
+
+Protocol V2 is fully backwards compatible with standard TAP 13. The Unicode markers are treated as comments by standard TAP parsers, so Protocol V2 output can be consumed by any TAP-compliant tool:
+
+```
+⟦TSTEST:PROTOCOL:2.0.0⟧    ← Ignored by standard TAP parsers
+TAP version 13               ← Standard TAP
+1..2                         ← Standard TAP
+ok 1 - test ⟦TSTEST:time:45⟧ ← TAP parsers see: "ok 1 - test"
+ok 2 - another test          ← Standard TAP
+```
 
 ## tapbundle Test Framework
 

test/decorator.all.ts

@@ -0,0 +1,91 @@
+import { tap, expect } from '../ts_tapbundle/index.js';
+
+/**
+ * Simple class decorator for testing decorator support across runtimes
+ */
+function testDecorator(target: any) {
+  target.decoratorApplied = true;
+  target.decoratorData = 'Decorator was applied successfully';
+  return target;
+}
+
+/**
+ * Method decorator for testing
+ */
+function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+  const originalMethod = descriptor.value;
+  descriptor.value = function (...args: any[]) {
+    const result = originalMethod.apply(this, args);
+    return `[logged] ${result}`;
+  };
+  return descriptor;
+}
+
+/**
+ * Parameter decorator for testing
+ */
+function validateParam(target: any, propertyKey: string, parameterIndex: number) {
+  // Mark that parameter validation decorator was applied
+  if (!target.decoratedParams) {
+    target.decoratedParams = {};
+  }
+  if (!target.decoratedParams[propertyKey]) {
+    target.decoratedParams[propertyKey] = [];
+  }
+  target.decoratedParams[propertyKey].push(parameterIndex);
+}
+
+/**
+ * Test class with decorators
+ */
+@testDecorator
+class TestClass {
+  public name: string = 'test';
+
+  @logMethod
+  public greet(message: string): string {
+    return `Hello, ${message}!`;
+  }
+
+  public getValue(): number {
+    return 42;
+  }
+
+  public testParams(@validateParam value: string): string {
+    return value;
+  }
+}
+
+// Tests
+tap.test('Class decorator should be applied', async () => {
+  expect((TestClass as any).decoratorApplied).toEqual(true);
+  expect((TestClass as any).decoratorData).toEqual('Decorator was applied successfully');
+});
+
+tap.test('Method decorator should modify method behavior', async () => {
+  const instance = new TestClass();
+  const result = instance.greet('World');
+  expect(result).toEqual('[logged] Hello, World!');
+});
+
+tap.test('Regular methods should work normally', async () => {
+  const instance = new TestClass();
+  expect(instance.getValue()).toEqual(42);
+  expect(instance.name).toEqual('test');
+});
+
+tap.test('Parameter decorator should be applied', async () => {
+  const decoratedParams = (TestClass.prototype as any).decoratedParams;
+  expect(decoratedParams).toBeDefined();
+  expect(decoratedParams.testParams).toBeDefined();
+  expect(decoratedParams.testParams).toContain(0);
+});
+
+tap.test('Decorator metadata preservation', async () => {
+  const instance = new TestClass();
+  expect(instance instanceof TestClass).toEqual(true);
+  expect(instance.constructor.name).toEqual('TestClass');
+  expect(instance.testParams('hello')).toEqual('hello');
+});
+
+export default tap.start();

test/test.example.latest.docker.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Sample Docker test file
+# This file demonstrates the naming pattern: test.{baseName}.{variant}.docker.sh
+# The variant "latest" maps to the Dockerfile in the project root
+
+echo "TAP version 13"
+echo "1..2"
+echo "ok 1 - Sample Docker test passes"
+echo "ok 2 - Docker environment is working"

ts/00_commitinfo_data.ts

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

ts/tstest.classes.runtime.bun.ts

@@ -69,6 +69,9 @@ export class BunRuntimeAdapter extends RuntimeAdapter {
 
     const args: string[] = ['run'];
 
+    // Note: Bun automatically discovers bunfig.toml in the current directory
+    // This ensures TypeScript decorator support is enabled if bunfig.toml is present
+
     // Add extra args
     if (mergedOptions.extraArgs && mergedOptions.extraArgs.length > 0) {
       args.push(...mergedOptions.extraArgs);

ts/tstest.classes.runtime.deno.ts

@@ -31,8 +31,20 @@ export class DenoRuntimeAdapter extends RuntimeAdapter {
    * Get default Deno options
    */
   protected getDefaultOptions(): DenoOptions {
+    // Auto-detect deno.json or deno.jsonc config file for TypeScript decorator support
+    let configPath: string | undefined;
+    const denoJsonPath = plugins.path.join(process.cwd(), 'deno.json');
+    const denoJsoncPath = plugins.path.join(process.cwd(), 'deno.jsonc');
+
+    if (plugins.smartfile.fs.fileExistsSync(denoJsonPath)) {
+      configPath = denoJsonPath;
+    } else if (plugins.smartfile.fs.fileExistsSync(denoJsoncPath)) {
+      configPath = denoJsoncPath;
+    }
+
     return {
       ...super.getDefaultOptions(),
+      configPath,
       permissions: [
         '--allow-read',
         '--allow-env',

ts/tstest.classes.runtime.docker.ts

@@ -0,0 +1,251 @@
+import * as plugins from './tstest.plugins.js';
+import { coloredString as cs } from '@push.rocks/consolecolor';
+import {
+  RuntimeAdapter,
+  type RuntimeOptions,
+  type RuntimeCommand,
+  type RuntimeAvailability,
+} from './tstest.classes.runtime.adapter.js';
+import { TapParser } from './tstest.classes.tap.parser.js';
+import { TsTestLogger } from './tstest.logging.js';
+import type { Runtime } from './tstest.classes.runtime.parser.js';
+import {
+  parseDockerTestFilename,
+  mapVariantToDockerfile,
+  isDockerTestFile
+} from './tstest.classes.runtime.parser.js';
+
+/**
+ * Docker runtime adapter
+ * Executes shell test files inside Docker containers
+ * Pattern: test.{variant}.docker.sh
+ * Variants map to Dockerfiles: latest -> Dockerfile, others -> Dockerfile_{variant}
+ */
+export class DockerRuntimeAdapter extends RuntimeAdapter {
+  readonly id: Runtime = 'node'; // Using 'node' temporarily as Runtime type doesn't include 'docker'
+  readonly displayName: string = 'Docker';
+
+  private builtImages: Set<string> = new Set(); // Track built images to avoid rebuilding
+
+  constructor(
+    private logger: TsTestLogger,
+    private smartshellInstance: any, // SmartShell instance from @push.rocks/smartshell
+    private timeoutSeconds: number | null,
+    private cwd: string
+  ) {
+    super();
+  }
+
+  /**
+   * Check if Docker CLI is available
+   */
+  async checkAvailable(): Promise<RuntimeAvailability> {
+    try {
+      const result = await this.smartshellInstance.exec('docker --version');
+
+      if (result.exitCode !== 0) {
+        return {
+          available: false,
+          error: 'Docker command failed',
+        };
+      }
+
+      // Extract version from output like "Docker version 24.0.5, build ced0996"
+      const versionMatch = result.stdout.match(/Docker version ([^,]+)/);
+      const version = versionMatch ? versionMatch[1] : 'unknown';
+
+      return {
+        available: true,
+        version,
+      };
+    } catch (error) {
+      return {
+        available: false,
+        error: `Docker not found: ${error.message}`,
+      };
+    }
+  }
+
+  /**
+   * Create command configuration for Docker test execution
+   * This is used for informational purposes
+   */
+  createCommand(testFile: string, options?: RuntimeOptions): RuntimeCommand {
+    const parsed = parseDockerTestFilename(testFile);
+    const dockerfilePath = mapVariantToDockerfile(parsed.variant, this.cwd);
+    const imageName = `tstest-${parsed.variant}`;
+
+    return {
+      command: 'docker',
+      args: [
+        'run',
+        '--rm',
+        '-v',
+        `${this.cwd}/test:/test`,
+        imageName,
+        'taprun',
+        `/test/${plugins.path.basename(testFile)}`
+      ],
+      env: {},
+      cwd: this.cwd,
+    };
+  }
+
+  /**
+   * Build a Docker image from the specified Dockerfile
+   */
+  private async buildDockerImage(dockerfilePath: string, imageName: string): Promise<void> {
+    // Check if image is already built
+    if (this.builtImages.has(imageName)) {
+      this.logger.tapOutput(`Using cached Docker image: ${imageName}`);
+      return;
+    }
+
+    // Check if Dockerfile exists
+    if (!await plugins.smartfile.fs.fileExists(dockerfilePath)) {
+      throw new Error(
+        `Dockerfile not found: ${dockerfilePath}\n` +
+        `Expected Dockerfile for Docker test variant.`
+      );
+    }
+
+    this.logger.tapOutput(`Building Docker image: ${imageName} from ${dockerfilePath}`);
+
+    try {
+      const buildResult = await this.smartshellInstance.exec(
+        `docker build -f ${dockerfilePath} -t ${imageName} ${this.cwd}`,
+        {
+          cwd: this.cwd,
+        }
+      );
+
+      if (buildResult.exitCode !== 0) {
+        throw new Error(`Docker build failed:\n${buildResult.stderr}`);
+      }
+
+      this.builtImages.add(imageName);
+      this.logger.tapOutput(`✅ Docker image built successfully: ${imageName}`);
+    } catch (error) {
+      throw new Error(`Failed to build Docker image: ${error.message}`);
+    }
+  }
+
+  /**
+   * Execute a Docker test file
+   */
+  async run(
+    testFile: string,
+    index: number,
+    total: number,
+    options?: RuntimeOptions
+  ): Promise<TapParser> {
+    this.logger.testFileStart(testFile, this.displayName, index, total);
+
+    // Parse the Docker test filename
+    const parsed = parseDockerTestFilename(testFile);
+    const dockerfilePath = mapVariantToDockerfile(parsed.variant, this.cwd);
+    const imageName = `tstest-${parsed.variant}`;
+
+    // Build the Docker image
+    await this.buildDockerImage(dockerfilePath, imageName);
+
+    // Prepare the test file path relative to the mounted directory
+    // We need to get the path relative to cwd
+    const absoluteTestPath = plugins.path.isAbsolute(testFile)
+      ? testFile
+      : plugins.path.join(this.cwd, testFile);
+
+    const relativeTestPath = plugins.path.relative(this.cwd, absoluteTestPath);
+
+    // Create TAP parser
+    const tapParser = new TapParser(testFile + ':docker', this.logger);
+
+    try {
+      // Build docker run command
+      const dockerArgs = [
+        'run',
+        '--rm',
+        '-v',
+        `${this.cwd}/test:/test`,
+        imageName,
+        'taprun',
+        `/test/${plugins.path.basename(testFile)}`
+      ];
+
+      this.logger.tapOutput(`Executing: docker ${dockerArgs.join(' ')}`);
+
+      // Execute the Docker container
+      const execPromise = this.smartshellInstance.execStreaming(
+        `docker ${dockerArgs.join(' ')}`,
+        {
+          cwd: this.cwd,
+        }
+      );
+
+      // Set up timeout if configured
+      let timeoutHandle: NodeJS.Timeout | null = null;
+      if (this.timeoutSeconds) {
+        timeoutHandle = setTimeout(() => {
+          this.logger.tapOutput(`⏱️  Test timeout (${this.timeoutSeconds}s) - killing container`);
+          // Try to kill any running containers with this image
+          this.smartshellInstance.exec(`docker ps -q --filter ancestor=${imageName} | xargs -r docker kill`);
+        }, this.timeoutSeconds * 1000);
+      }
+
+      // Stream output to TAP parser line by line
+      execPromise.childProcess.stdout.on('data', (data: Buffer) => {
+        const output = data.toString();
+        const lines = output.split('\n');
+        for (const line of lines) {
+          if (line.trim()) {
+            tapParser.handleTapLog(line);
+          }
+        }
+      });
+
+      execPromise.childProcess.stderr.on('data', (data: Buffer) => {
+        const output = data.toString();
+        this.logger.tapOutput(cs(`[stderr] ${output}`, 'orange'));
+      });
+
+      // Wait for completion
+      const result = await execPromise;
+
+      // Clear timeout
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+
+      if (result.exitCode !== 0) {
+        this.logger.tapOutput(cs(`❌ Docker test failed with exit code ${result.exitCode}`, 'red'));
+      }
+
+      // Evaluate final result
+      await tapParser.evaluateFinalResult();
+
+    } catch (error) {
+      this.logger.tapOutput(cs(`❌ Error running Docker test: ${error.message}`, 'red'));
+      // Add a failing test result to the parser
+      tapParser.handleTapLog('not ok 1 - Docker test execution failed');
+      await tapParser.evaluateFinalResult();
+    }
+
+    return tapParser;
+  }
+
+  /**
+   * Clean up built Docker images (optional, can be called at end of test suite)
+   */
+  async cleanup(): Promise<void> {
+    for (const imageName of this.builtImages) {
+      try {
+        this.logger.tapOutput(`Removing Docker image: ${imageName}`);
+        await this.smartshellInstance.exec(`docker rmi ${imageName}`);
+      } catch (error) {
+        // Ignore cleanup errors
+        this.logger.tapOutput(cs(`Warning: Failed to remove image ${imageName}: ${error.message}`, 'orange'));
+      }
+    }
+    this.builtImages.clear();
+  }
+}

ts/tstest.classes.runtime.parser.ts

@@ -29,7 +29,7 @@ export interface ParserConfig {
 
 const KNOWN_RUNTIMES: Set<string> = new Set(['node', 'chromium', 'deno', 'bun']);
 const KNOWN_MODIFIERS: Set<string> = new Set(['nonci']);
-const VALID_EXTENSIONS: Set<string> = new Set(['ts', 'tsx', 'mts', 'cts']);
+const VALID_EXTENSIONS: Set<string> = new Set(['ts', 'tsx', 'mts', 'cts', 'sh']);
 const ALL_RUNTIMES: Runtime[] = ['node', 'chromium', 'deno', 'bun'];
 
 // Legacy mappings for backwards compatibility
@@ -228,3 +228,81 @@ export function getLegacyMigrationTarget(fileName: string): string | null {
 
   return parts.join('.');
 }
+
+/**
+ * Docker test file information
+ */
+export interface DockerTestFileInfo {
+  baseName: string;
+  variant: string;
+  isDockerTest: true;
+  original: string;
+}
+
+/**
+ * Check if a filename matches the Docker test pattern: *.{variant}.docker.sh
+ * Examples: test.latest.docker.sh, test.integration.npmci.docker.sh
+ */
+export function isDockerTestFile(fileName: string): boolean {
+  // Must end with .docker.sh
+  if (!fileName.endsWith('.docker.sh')) {
+    return false;
+  }
+
+  // Extract filename from path if needed
+  const name = fileName.split('/').pop() || fileName;
+
+  // Must have at least 3 parts: [baseName, variant, docker, sh]
+  const parts = name.split('.');
+  return parts.length >= 4 && parts[parts.length - 2] === 'docker' && parts[parts.length - 1] === 'sh';
+}
+
+/**
+ * Parse a Docker test filename to extract variant and base name
+ * Pattern: test.{baseName}.{variant}.docker.sh
+ * Examples:
+ *   - test.latest.docker.sh -> { baseName: 'test', variant: 'latest' }
+ *   - test.integration.npmci.docker.sh -> { baseName: 'test.integration', variant: 'npmci' }
+ */
+export function parseDockerTestFilename(filePath: string): DockerTestFileInfo {
+  // Extract just the filename from the path
+  const fileName = filePath.split('/').pop() || filePath;
+  const original = fileName;
+
+  if (!isDockerTestFile(fileName)) {
+    throw new Error(`Not a valid Docker test file: "${fileName}". Expected pattern: *.{variant}.docker.sh`);
+  }
+
+  // Remove .docker.sh suffix
+  const withoutSuffix = fileName.slice(0, -10); // Remove '.docker.sh'
+  const tokens = withoutSuffix.split('.');
+
+  if (tokens.length === 0) {
+    throw new Error(`Invalid Docker test file: empty basename in "${fileName}"`);
+  }
+
+  // Last token before .docker.sh is the variant
+  const variant = tokens[tokens.length - 1];
+
+  // Everything else is the base name
+  const baseName = tokens.slice(0, -1).join('.');
+
+  return {
+    baseName: baseName || 'test',
+    variant,
+    isDockerTest: true,
+    original,
+  };
+}
+
+/**
+ * Map a Docker variant to its corresponding Dockerfile path
+ * "latest" -> "Dockerfile"
+ * Other variants -> "Dockerfile_{variant}"
+ */
+export function mapVariantToDockerfile(variant: string, baseDir: string): string {
+  if (variant === 'latest') {
+    return `${baseDir}/Dockerfile`;
+  }
+  return `${baseDir}/Dockerfile_${variant}`;
+}

ts/tstest.classes.testdirectory.ts

@@ -74,12 +74,20 @@ export class TestDirectory {
       case TestExecutionMode.DIRECTORY:
         // Directory mode - now recursive with ** pattern
         const dirPath = plugins.path.join(this.cwd, this.testPath);
-        const testPattern = '**/test*.ts';
 
-        const testFiles = await plugins.smartfile.fs.listFileTree(dirPath, testPattern);
+        // Search for both TypeScript test files and Docker shell test files
+        const tsPattern = '**/test*.ts';
+        const dockerPattern = '**/*.docker.sh';
+
+        const [tsFiles, dockerFiles] = await Promise.all([
+          plugins.smartfile.fs.listFileTree(dirPath, tsPattern),
+          plugins.smartfile.fs.listFileTree(dirPath, dockerPattern),
+        ]);
+
+        const allTestFiles = [...tsFiles, ...dockerFiles];
 
         this.testfileArray = await Promise.all(
-          testFiles.map(async (filePath) => {
+          allTestFiles.map(async (filePath) => {
             const absolutePath = plugins.path.isAbsolute(filePath)
               ? filePath
               : plugins.path.join(dirPath, filePath);

ts/tstest.classes.tstest.ts

@@ -11,12 +11,13 @@ import { TsTestLogger } from './tstest.logging.js';
 import type { LogOptions } from './tstest.logging.js';
 
 // Runtime adapters
-import { parseTestFilename } from './tstest.classes.runtime.parser.js';
+import { parseTestFilename, isDockerTestFile, parseDockerTestFilename } from './tstest.classes.runtime.parser.js';
 import { RuntimeAdapterRegistry } from './tstest.classes.runtime.adapter.js';
 import { NodeRuntimeAdapter } from './tstest.classes.runtime.node.js';
 import { ChromiumRuntimeAdapter } from './tstest.classes.runtime.chromium.js';
 import { DenoRuntimeAdapter } from './tstest.classes.runtime.deno.js';
 import { BunRuntimeAdapter } from './tstest.classes.runtime.bun.js';
+import { DockerRuntimeAdapter } from './tstest.classes.runtime.docker.js';
 
 export class TsTest {
   public testDir: TestDirectory;
@@ -37,6 +38,7 @@ export class TsTest {
   public tsbundleInstance = new plugins.tsbundle.TsBundle();
 
   public runtimeRegistry = new RuntimeAdapterRegistry();
+  public dockerAdapter: DockerRuntimeAdapter | null = null;
 
   constructor(cwdArg: string, testPathArg: string, executionModeArg: TestExecutionMode, logOptions: LogOptions = {}, tags: string[] = [], startFromFile: number | null = null, stopAtFile: number | null = null, timeoutSeconds: number | null = null) {
     this.executionMode = executionModeArg;
@@ -60,6 +62,14 @@ export class TsTest {
     this.runtimeRegistry.register(
       new BunRuntimeAdapter(this.logger, this.smartshellInstance, this.timeoutSeconds, this.filterTags)
     );
+
+    // Initialize Docker adapter
+    this.dockerAdapter = new DockerRuntimeAdapter(
+      this.logger,
+      this.smartshellInstance,
+      this.timeoutSeconds,
+      cwdArg
+    );
   }
 
   /**
@@ -211,8 +221,14 @@ export class TsTest {
   }
   
   private async runSingleTest(fileNameArg: string, fileIndex: number, totalFiles: number, tapCombinator: TapCombinator) {
-    // Parse the filename to determine runtimes and modifiers
     const fileName = plugins.path.basename(fileNameArg);
+
+    // Check if this is a Docker test file
+    if (isDockerTestFile(fileName)) {
+      return await this.runDockerTest(fileNameArg, fileIndex, totalFiles, tapCombinator);
+    }
+
+    // Parse the filename to determine runtimes and modifiers (for TypeScript tests)
     const parsed = parseTestFilename(fileName, { strictUnknownRuntime: false });
 
     // Check for nonci modifier in CI environment
@@ -258,6 +274,28 @@ export class TsTest {
     }
   }
 
+  /**
+   * Execute a Docker test file
+   */
+  private async runDockerTest(
+    fileNameArg: string,
+    fileIndex: number,
+    totalFiles: number,
+    tapCombinator: TapCombinator
+  ): Promise<void> {
+    if (!this.dockerAdapter) {
+      this.logger.tapOutput(cs('❌ Docker adapter not initialized', 'red'));
+      return;
+    }
+
+    try {
+      const tapParser = await this.dockerAdapter.run(fileNameArg, fileIndex, totalFiles);
+      tapCombinator.addTapParser(tapParser);
+    } catch (error) {
+      this.logger.tapOutput(cs(`❌ Docker test failed: ${error.message}`, 'red'));
+    }
+  }
+
   public async runInNode(fileNameArg: string, index: number, total: number): Promise<TapParser> {
     this.logger.testFileStart(fileNameArg, 'node.js', index, total);
     const tapParser = new TapParser(fileNameArg + ':node', this.logger);