tstest/readme.hints.md

Architecture Overview

Project Structure

This project integrates tstest with tapbundle through a modular architecture:

1. tstest (/ts/) - The test runner that discovers and executes test files
2. tapbundle (/ts_tapbundle/) - The TAP testing framework for writing tests
3. tapbundle_node (/ts_tapbundle_node/) - Node.js-specific testing utilities

How Components Work Together

Test Execution Flow

1. CLI Entry Point (cli.js <20> cli.ts.js <20> cli.child.ts)

   • The CLI uses tsx to run TypeScript files directly
   • Accepts glob patterns to find test files
   • Supports options like --verbose, --quiet, --web

2. Test Discovery

   • tstest scans for test files matching the provided pattern
   • Defaults to test/**/*.ts when no pattern is specified
   • Supports both file and directory modes

3. Test Runner

   • Each test file imports tap and expect from tapbundle
   • Tests are written using tap.test() with async functions
   • Browser tests are compiled with esbuild and run in Chromium via Puppeteer

Key Integration Points

1. Import Structure

   • Test files import from local tapbundle: import { tap, expect } from '../../ts_tapbundle/index.js'
   • Node-specific tests also import from tapbundle_node: import { tapNodeTools } from '../../ts_tapbundle_node/index.js'

2. WebHelpers

   • Browser tests can use webhelpers for DOM manipulation
   • webhelpers.html - Template literal for creating HTML strings
   • webhelpers.fixture - Creates DOM elements from HTML strings
   • Automatically detects browser environment and only enables in browser context

3. Build System

   • Uses tsbuild tsfolders to compile TypeScript
   • Maintains separate output directories: /dist_ts/, /dist_ts_tapbundle/, /dist_ts_tapbundle_node/
   • Compilation order is resolved automatically based on dependencies

Test Scripts

The package.json defines several test scripts:

• test - Builds and runs all tests (tapbundle and tstest)
• test:tapbundle - Runs tapbundle framework tests
• test:tstest - Runs tstest's own tests
• Both support :verbose variants for detailed output

Environment Detection

The framework automatically detects the runtime environment:

• Node.js tests run directly via tsx
• Browser tests are compiled and served via a local server
• WebHelpers are only enabled in browser environment

This architecture allows for seamless testing across both Node.js and browser environments while maintaining a clean separation of concerns.

Logging System

Log File Naming (Fixed in v1.9.1)

When using the --logfile flag, tstest creates log files in .nogit/testlogs/. The log file naming was updated to preserve directory structure and prevent collisions:

• Old behavior: test/tapbundle/test.ts → .nogit/testlogs/test.log
• New behavior: test/tapbundle/test.ts → .nogit/testlogs/test__tapbundle__test.log

This fix ensures that test files with the same basename in different directories don't overwrite each other's logs. The implementation:

1. Takes the relative path from the current working directory
2. Replaces path separators (/) with double underscores (__)
3. Removes the .ts extension
4. Creates a flat filename that preserves the directory structure

Test Timing Display (Fixed in v1.9.2)

Fixed an issue where test timing was displayed incorrectly with duplicate values like:

• Before: ✅ test name # time=133ms (0ms)
• After: ✅ test name (133ms)

The issue was in the TAP parser regex which was greedily capturing the entire line including the TAP timing comment. Changed the regex from (.*) to (.*?) to make it non-greedy, properly separating the test name from the timing metadata.

Protocol Limitations and Improvements

Current TAP Protocol Issues

The current implementation uses standard TAP format with metadata in comments:

ok 1 - test name # time=123ms

This has several limitations:

1. Delimiter Conflict: Test descriptions containing # can break parsing
2. Regex Fragility: Complex regex patterns that are hard to maintain
3. Limited Metadata: Difficult to add rich error information or custom data

Planned Protocol V2

A new internal protocol is being designed that will:

• Use Unicode delimiters ⟦TSTEST:⟧ that won't conflict with test content
• Support structured JSON metadata
• Allow rich error reporting with stack traces and diffs
• Maintain backwards compatibility during migration

See readme.protocol.md for the full specification and tapbundle.protocols.ts for the implementation utilities.