1.11.3

fix(tstest): Add timeout warning for long-running tests and introduce local settings configuration
1.11.2
2025-05-24 10:52:15 +00:00 · 2025-05-24 10:52:15 +00:00 · 2025-05-24 02:22:34 +00:00 · 2025-05-24 02:22:34 +00:00 · 2025-05-24 01:42:24 +00:00 · 2025-05-24 01:42:24 +00:00
66 changed files with 4588 additions and 1633 deletions
--- a/.gitignore
+++ b/.gitignore
@ -17,4 +17,4 @@ node_modules/
 dist/
 dist_*/

-# custom
+# custom
--- a/.npmrc
+++ b/.npmrc
@ -0,0 +1 @@
+registry=https://registry.npmjs.org
--- a/changelog.md
+++ b/changelog.md
@ -1,5 +1,158 @@
 # Changelog

+## 2025-05-24 - 1.11.3 - fix(tstest)
+Add timeout warning for long-running tests and introduce local settings configuration
+
+- Add .claude/settings.local.json with permission configuration for local development
+- Implement a timeout warning timer that notifies when tests run longer than 1 minute without an explicit timeout
+- Clear the timeout warning timer upon test completion
+- Remove unused import of logPrefixes in tstest.classes.tstest.ts
+
+## 2025-05-24 - 1.11.2 - fix(tstest)
+Improve timeout and error handling in test execution along with TAP parser timeout logic improvements.
+
+- In the TAP parser, ensure that expected tests are properly set when no tests are defined to avoid false negatives on timeout.
+- Use smartshell's terminate method and fallback kill to properly stop the entire process tree on timeout.
+- Clean up browser, server, and WebSocket instances reliably even when a timeout occurs.
+- Minor improvements in log file filtering and error logging for better clarity.
+
+## 2025-05-24 - 1.11.1 - fix(tstest)
+Clear timeout identifiers after successful test execution and add local CLAUDE settings
+
+- Ensure timeout IDs are cleared when tests complete to prevent lingering timeouts
+- Add .claude/settings.local.json with updated permission settings for CLI commands
+
+## 2025-05-24 - 1.11.0 - feat(cli)
+Add new timeout and file range options with enhanced logfile diff logging
+
+- Introduce --timeout <seconds> option to safeguard tests from running too long
+- Add --startFrom and --stopAt options to control the range of test files executed
+- Enhance logfile organization by automatically moving previous logs and generating diff reports for failed or changed test outputs
+- Update CLI argument parsing and internal timeout handling for both Node.js and browser tests
+
+## 2025-05-24 - 1.10.2 - fix(tstest-logging)
+Improve log file handling with log rotation and diff reporting
+
+- Add .claude/settings.local.json to configure allowed shell and web operations
+- Introduce movePreviousLogFiles function to archive previous log files when --logfile is used
+- Enhance logging to generate error copies and diff reports between current and previous logs
+- Add type annotations for console overrides in browser evaluations for improved stability
+
+## 2025-05-23 - 1.10.1 - fix(tstest)
+Improve file range filtering and summary logging by skipping test files outside the specified range and reporting them in the final summary.
+
+- Introduce runSingleTestOrSkip to check file index against startFrom/stopAt values.
+- Log skipped files with appropriate messages and add them to the summary.
+- Update the logger to include total skipped files in the test summary.
+- Add permission settings in .claude/settings.local.json to support new operations.
+
+## 2025-05-23 - 1.10.0 - feat(cli)
+Add --startFrom and --stopAt options to filter test files by range
+
+- Introduced CLI options --startFrom and --stopAt in ts/index.ts for selective test execution
+- Added validation to ensure provided range values are positive and startFrom is not greater than stopAt
+- Propagated file range filtering into test grouping in tstest.classes.tstest.ts, applying the range filter across serial and parallel groups
+- Updated usage messages to include the new options
+
+## 2025-05-23 - 1.9.4 - fix(docs)
+Update documentation and configuration for legal notices and CI permissions. This commit adds a new local settings file for tool permissions, refines the legal and trademark sections in the readme, and improves glob test files with clearer log messages.
+
+- Added .claude/settings.local.json to configure permissions for various CLI commands
+- Revised legal and trademark documentation in the readme to clarify company ownership and usage guidelines
+- Updated glob test files with improved console log messages for better clarity during test discovery
+
+## 2025-05-23 - 1.9.3 - fix(tstest)
+Fix test timing display issue and update TAP protocol documentation
+
+- Changed TAP parser regex to non-greedy pattern to correctly separate test timing metadata
+- Enhanced readme.hints.md with detailed explanation of test timing fix and planned protocol upgrades
+- Updated readme.md with improved usage examples for tapbundle and comprehensive test framework documentation
+- Added new protocol design document (readme.protocol.md) and improvement plan (readme.plan.md) outlining future changes
+- Introduced .claude/settings.local.json update for npm and CLI permissions
+- Exported protocol utilities and added tapbundle protocol implementation for future enhancements
+
+## 2025-05-23 - 1.9.2 - fix(logging)
+Fix log file naming to prevent collisions and update logging system documentation.
+
+- Enhance safe filename generation in tstest logging to preserve directory structure using double underscores.
+- Update readme.hints.md to include detailed logging system documentation and behavior.
+- Add .claude/settings.local.json with updated permissions for build tools.
+
+## 2025-05-23 - 1.9.1 - fix(dependencies)
+Update dependency versions and add local configuration files
+
+- Bump @git.zone/tsbuild from ^2.5.1 to ^2.6.3
+- Bump @types/node from ^22.15.18 to ^22.15.21
+- Bump @push.rocks/smartexpect from ^2.4.2 to ^2.5.0
+- Bump @push.rocks/smartfile from ^11.2.0 to ^11.2.3
+- Bump @push.rocks/smartlog from ^3.1.1 to ^3.1.8
+- Add .npmrc with npm registry configuration
+- Add .claude/settings.local.json for local permissions
+
+## 2025-05-16 - 1.9.0 - feat(docs)
+Update documentation to embed tapbundle and clarify module exports for browser compatibility; also add CI permission settings.
+
+- Embed tapbundle directly into tstest to simplify usage and ensure browser support.
+- Update import paths in examples from '@push.rocks/tapbundle' to '@git.zone/tstest/tapbundle'.
+- Revise the changelog to reflect version 1.8.0 improvements including enhanced test lifecycle hooks and parallel execution fixes.
+- Add .claude/settings.local.json to configure CI-related permissions and tool operations.
+
+## 2025-05-16 - 1.8.0 - feat(documentation)
+Enhance README with detailed test features and update local settings for build permissions.
+
+- Expanded the documentation to include tag filtering, parallel test execution groups, lifecycle hooks, snapshot testing, timeout control, retry logic, and test fixtures
+- Updated .claude/settings.local.json to allow additional permissions for various build and test commands
+
+## 2025-05-16 - 1.7.0 - feat(tstest)
+Enhance tstest with fluent API, suite grouping, tag filtering, fixture & snapshot testing, and parallel execution improvements
+
+- Updated npm scripts to run tests in verbose mode and support glob patterns with quotes
+- Introduced tag filtering support (--tags) in the CLI to run tests by specified tags
+- Implemented fluent syntax methods (tags, priority, retry, timeout) for defining tests and applying settings
+- Added test suite grouping with describe(), along with beforeEach and afterEach lifecycle hooks
+- Integrated a fixture system and snapshot testing via TapTools with base64 snapshot communication
+- Enhanced TAP parser regex, error collection, and snapshot handling for improved debugging
+- Improved parallel test execution by grouping files with a 'para__' pattern and running them concurrently
+
+## 2025-05-15 - 1.6.0 - feat(package)
+Revamp package exports and update permissions with an extensive improvement plan for test runner enhancements.
+
+- Replaced 'main' and 'typings' in package.json with explicit exports for improved module resolution.
+- Added .claude/settings.local.json to configure permissions for bash commands and web fetches.
+- Updated readme.plan.md with a comprehensive roadmap covering enhanced error reporting, rich test metadata, nested test suites, and advanced test features.
+
+## 2025-05-15 - 1.5.0 - feat(cli)
+Improve test runner configuration: update test scripts, reorganize test directories, update dependencies and add local settings for command permissions.
+
+- Updated package.json scripts to use pnpm and separate commands for tapbundle and tstest.
+- Reorganized tests into dedicated directories (test/tapbundle and test/tstest) and removed deprecated test files.
+- Refactored import paths and bumped dependency versions in tapbundle, tstest, and associated node utilities.
+- Added .claude/settings.local.json to configure local permissions for bash and web fetch commands.
+- Introduced ts/tspublish.json to define publish order.
+
+## 2025-05-15 - 1.4.0 - feat(logging)
+Display failed test console logs in default mode
+
+- Introduce log buffering in TsTestLogger to capture console output for failed tests
+- Enhance TapParser to collect and display error details when tests fail
+- Update README and project plan to document log improvements for debugging
+
+## 2025-05-15 - 1.3.1 - fix(settings)
+Add local permissions configuration and remove obsolete test output log
+
+- Added .claude/settings.local.json to configure allowed permissions for web fetch and bash commands
+- Removed test-output.log to eliminate accidental commit of test artifacts
+
+## 2025-05-15 - 1.3.0 - feat(logger)
+Improve logging output and add --logfile support for persistent logs
+
+- Add new .claude/settings.local.json with logging permissions configuration
+- Remove obsolete readme.plan.md
+- Introduce test/test.console.ts to capture and display console outputs during tests
+- Update CLI in ts/index.ts to replace '--log-file' with '--logfile' flag
+- Enhance TsTestLogger to support file logging, clean ANSI sequences, and improved JSON output
+- Forward TAP protocol logs to testConsoleOutput in TapParser for better console distinction
+
 ## 2025-05-15 - 1.2.0 - feat(logging)
 Improve logging output, CLI option parsing, and test report formatting.

--- a/19
+++ b/19
@ -0,0 +1,19 @@
+Copyright (c) 2014 Task Venture Capital GmbH (hello@task.vc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/package.json
+++ b/package.json
@ -1,10 +1,13 @@
 {
  "name": "@git.zone/tstest",
-  "version": "1.2.0",
+  "version": "1.11.3",
  "private": false,
  "description": "a test utility to run tests that match test/**/*.ts",
-  "main": "dist_ts/index.js",
-  "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": "./dist_ts/index.js",
+    "./tapbundle": "./dist_ts_tapbundle/index.js",
+    "./tapbundle_node": "./dist_ts_tapbundle_node/index.js"
+  },
  "type": "module",
  "author": "Lossless GmbH",
  "license": "MIT",
@ -12,29 +15,39 @@
    "tstest": "./cli.js"
  },
  "scripts": {
-    "test": "(npm run cleanUp && npm run prepareTest && npm run tstest)",
-    "prepareTest": "git clone https://gitlab.com/sandboxzone/sandbox-npmts.git .nogit/sandbox-npmts && cd .nogit/sandbox-npmts && npm install",
-    "tstest": "cd .nogit/sandbox-npmts && node ../../cli.ts.js test/ --web",
-    "cleanUp": "rm -rf .nogit/sandbox-npmts",
-    "build": "(tsbuild --web --allowimplicitany  --skiplibcheck)",
+    "test": "pnpm run build && pnpm run test:tapbundle:verbose && pnpm run test:tstest:verbose",
+    "test:tapbundle": "tsx ./cli.child.ts \"test/tapbundle/**/*.ts\"",
+    "test:tapbundle:verbose": "tsx ./cli.child.ts \"test/tapbundle/**/*.ts\" --verbose",
+    "test:tstest": "tsx ./cli.child.ts \"test/tstest/**/*.ts\"",
+    "test:tstest:verbose": "tsx ./cli.child.ts \"test/tstest/**/*.ts\" --verbose",
+    "build": "(tsbuild tsfolders)",
    "buildDocs": "tsdoc"
  },
  "devDependencies": {
-    "@git.zone/tsbuild": "^2.5.1",
-    "@types/node": "^22.15.18"
+    "@git.zone/tsbuild": "^2.6.3",
+    "@types/node": "^22.15.21"
  },
  "dependencies": {
    "@api.global/typedserver": "^3.0.74",
    "@git.zone/tsbundle": "^2.2.5",
    "@git.zone/tsrun": "^1.3.3",
    "@push.rocks/consolecolor": "^2.0.2",
+    "@push.rocks/qenv": "^6.1.0",
    "@push.rocks/smartbrowser": "^2.0.8",
+    "@push.rocks/smartcrypto": "^2.0.4",
    "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartfile": "^11.2.0",
-    "@push.rocks/smartlog": "^3.0.9",
+    "@push.rocks/smartenv": "^5.0.12",
+    "@push.rocks/smartexpect": "^2.5.0",
+    "@push.rocks/smartfile": "^11.2.3",
+    "@push.rocks/smartjson": "^5.0.20",
+    "@push.rocks/smartlog": "^3.1.8",
+    "@push.rocks/smartmongo": "^2.0.12",
+    "@push.rocks/smartpath": "^5.0.18",
    "@push.rocks/smartpromise": "^4.2.3",
+    "@push.rocks/smartrequest": "^2.1.0",
+    "@push.rocks/smarts3": "^2.2.5",
    "@push.rocks/smartshell": "^3.2.3",
-    "@push.rocks/tapbundle": "^6.0.3",
+    "@push.rocks/smarttime": "^4.1.1",
    "@types/ws": "^8.18.1",
    "figures": "^6.1.0",
    "ws": "^8.18.2"
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/readme.hints.md
+++ b/readme.hints.md
@ -0,0 +1,107 @@
+# 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.
--- a/readme.md
+++ b/readme.md
@ -1,61 +1,788 @@
 # @gitzone/tstest
-a test utility to run tests that match test/**/*.ts
+🧪 **A powerful, modern test runner for TypeScript** - making your test runs beautiful and informative!

 ## Availabililty and Links
 * [npmjs.org (npm package)](https://www.npmjs.com/package/@gitzone/tstest)
-* [gitlab.com (source)](https://gitlab.com/gitzone/tstest)
-* [github.com (source mirror)](https://github.com/gitzone/tstest)
-* [docs (typedoc)](https://gitzone.gitlab.io/tstest/)
+* [code.foss.global (source)](https://code.foss.global/gitzone/tstest)

-## Status for master
+## Why tstest?

-Status Category | Status Badge
-- | --
-GitLab Pipelines | [![pipeline status](https://gitlab.com/gitzone/tstest/badges/master/pipeline.svg)](https://lossless.cloud)
-GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/gitzone/tstest/badges/master/coverage.svg)](https://lossless.cloud)
-npm | [![npm downloads per month](https://badgen.net/npm/dy/@gitzone/tstest)](https://lossless.cloud)
-Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/gitzone/tstest)](https://lossless.cloud)
-TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)
-node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/)
-Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)
-PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@gitzone/tstest)](https://lossless.cloud)
-PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@gitzone/tstest)](https://lossless.cloud)
-BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@gitzone/tstest)](https://lossless.cloud)
-Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud)
+**tstest** is a TypeScript test runner that makes testing delightful. It's designed for modern development workflows with beautiful output, flexible test execution, and powerful features that make debugging a breeze.
+
+### ✨ Key Features
+
+- 🎯 **Smart Test Execution** - Run all tests, single files, or use glob patterns
+- 🎨 **Beautiful Output** - Color-coded results with emojis and clean formatting
+- 📊 **Multiple Output Modes** - Choose from normal, quiet, verbose, or JSON output
+- 🔍 **Automatic Discovery** - Finds all your test files automatically
+- 🌐 **Cross-Environment** - Supports Node.js and browser testing
+- 📝 **Detailed Logging** - Optional file logging for debugging
+- ⚡ **Performance Metrics** - See which tests are slow
+- 🤖 **CI/CD Ready** - JSON output mode for automation
+- 🏷️ **Tag-based Filtering** - Run only tests with specific tags
+- 🎯 **Parallel Test Execution** - Run tests in parallel groups
+- 🔧 **Test Lifecycle Hooks** - beforeEach/afterEach support
+- 📸 **Snapshot Testing** - Compare test outputs with saved snapshots
+- ⏳ **Timeout Control** - Set custom timeouts for tests
+- 🔁 **Retry Logic** - Automatically retry failing tests
+- 🛠️ **Test Fixtures** - Create reusable test data
+- 📦 **Browser-Compatible** - Full browser support with embedded tapbundle
+
+## Installation
+
+```bash
+npm install --save-dev @gitzone/tstest
+# or with pnpm
+pnpm add -D @gitzone/tstest
+```

 ## Usage

-## cli usage
+### Basic Test Execution

-lets assume we have a directory called test/ where all our tests arae defined. Simply type
-
-```
+```bash
+# Run all tests in a directory
 tstest test/
+
+# Run a specific test file
+tstest test/test.mycomponent.ts
+
+# Use glob patterns
+tstest "test/**/*.spec.ts"
+tstest "test/unit/*.ts"
 ```

-to run all tests.
+### Execution Modes

-## Syntax
+**tstest** intelligently detects how you want to run your tests:

-tstest supports tap syntax. In other words your testfiles are run in a subprocess, and the console output contains trigger messages for tstest to determine test status. Inside your testfile you should use `@pushrocks/tapbundle` for the best results.
+1. **Directory mode** - Recursively finds all test files
+2. **File mode** - Runs a single test file
+3. **Glob mode** - Uses pattern matching for flexible test selection

-## Environments
+### Command Line Options

-tstest supports different environments:
+| Option | Description |
+|--------|-------------|
+| `--quiet`, `-q` | Minimal output - perfect for CI environments |
+| `--verbose`, `-v` | Show all console output from tests |
+| `--no-color` | Disable colored output |
+| `--json` | Output results as JSON |
+| `--logfile` | Save detailed logs with automatic error and diff tracking |
+| `--tags <tags>` | Run only tests with specific tags (comma-separated) |
+| `--timeout <seconds>` | Timeout test files after specified seconds |
+| `--startFrom <n>` | Start running from test file number n |
+| `--stopAt <n>` | Stop running at test file number n |

- a testfile called `test-something.node.ts` will be run in node
- a testfile called `test-something.chrome.ts` will be run in chrome environment (bundled through parcel and run through puppeteer)
- a testfile called `test-something.both.ts` will be run in node an chrome, which is good for isomorphic packages.
+### Example Outputs

-> note: there is alpha support for the deno environment by naming a file test-something.deno.ts
+#### Normal Output (Default)
+```
+🔍 Test Discovery
+   Mode: directory
+   Pattern: test
+   Found: 4 test file(s)

-## Contribution
+▶️  test/test.ts (1/4)
+   Runtime: node.js
+   ✅ prepare test (1ms)
+   Summary: 1/1 PASSED

-We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
+📊 Test Summary
+┌────────────────────────────────┐
+│ Total Files:                 4 │
+│ Total Tests:                 4 │
+│ Passed:                      4 │
+│ Failed:                      0 │
+│ Duration:                542ms │
+└────────────────────────────────┘

-For further information read the linked docs at the top of this readme.
+ALL TESTS PASSED! 🎉
+```

-> MIT licensed | **&copy;** [Lossless GmbH](https://lossless.gmbh)
-| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
+#### Quiet Mode
+```
+Found 4 tests
+✅ test functionality works
+✅ api calls return expected data
+✅ error handling works correctly
+✅ performance is within limits

-[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)
+Summary: 4/4 | 542ms | PASSED
+```
+
+#### Verbose Mode
+Shows all console output from your tests, making debugging easier:
+```
+▶️  test/api.test.ts (1/1)
+   Runtime: node.js
+   Making API call to /users...
+   Response received: 200 OK
+   Processing user data...
+   ✅ api calls return expected data (145ms)
+   Summary: 1/1 PASSED
+```
+
+#### JSON Mode
+Perfect for CI/CD pipelines:
+```json
+{"event":"discovery","count":4,"pattern":"test","executionMode":"directory"}
+{"event":"fileStart","filename":"test/test.ts","runtime":"node.js","index":1,"total":4}
+{"event":"testResult","testName":"prepare test","passed":true,"duration":1}
+{"event":"summary","summary":{"totalFiles":4,"totalTests":4,"totalPassed":4,"totalFailed":0,"totalDuration":542}}
+```
+
+## Test File Naming Conventions
+
+tstest supports different test environments through file naming:
+
+| Pattern | Environment | Example |
+|---------|-------------|---------|
+| `*.ts` | Node.js (default) | `test.basic.ts` |
+| `*.node.ts` | Node.js only | `test.api.node.ts` |
+| `*.chrome.ts` | Chrome browser | `test.dom.chrome.ts` |
+| `*.browser.ts` | Browser environment | `test.ui.browser.ts` |
+| `*.both.ts` | Both Node.js and browser | `test.isomorphic.both.ts` |
+
+### Writing Tests with tapbundle
+
+tstest includes tapbundle, a powerful TAP-based test framework. Import it from the embedded tapbundle:
+
+```typescript
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+
+tap.test('my awesome test', async () => {
+  const result = await myFunction();
+  expect(result).toEqual('expected value');
+});
+
+tap.start();
+```
+
+**Module Exports**
+
+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
+
+## tapbundle Test Framework
+
+### Basic Test Syntax
+
+```typescript
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+// Basic test
+tap.test('should perform basic arithmetic', async () => {
+  expect(2 + 2).toEqual(4);
+});
+
+// Async test with tools
+tap.test('async operations', async (tools) => {
+  await tools.delayFor(100); // delay for 100ms
+  const result = await fetchData();
+  expect(result).toBeDefined();
+});
+
+// Start test execution
+tap.start();
+```
+
+### Test Modifiers and Chaining
+
+```typescript
+// Skip a test
+tap.skip.test('not ready yet', async () => {
+  // This test will be skipped
+});
+
+// Run only this test (exclusive)
+tap.only.test('focus on this', async () => {
+  // Only this test will run
+});
+
+// Todo test
+tap.todo('implement later', async () => {
+  // Marked as todo
+});
+
+// Chaining modifiers
+tap.timeout(5000)
+   .retry(3)
+   .tags('api', 'integration')
+   .test('complex test', async (tools) => {
+     // Test with 5s timeout, 3 retries, and tags
+   });
+```
+
+### Test Organization with describe()
+
+```typescript
+tap.describe('User Management', () => {
+  let testDatabase;
+  
+  tap.beforeEach(async () => {
+    testDatabase = await createTestDB();
+  });
+  
+  tap.afterEach(async () => {
+    await testDatabase.cleanup();
+  });
+  
+  tap.test('should create user', async () => {
+    const user = await testDatabase.createUser({ name: 'John' });
+    expect(user.id).toBeDefined();
+  });
+  
+  tap.describe('User Permissions', () => {
+    tap.test('should set admin role', async () => {
+      // Nested describe blocks
+    });
+  });
+});
+```
+
+### Test Tools (Available in Test Function)
+
+Every test function receives a `tools` parameter with utilities:
+
+```typescript
+tap.test('using test tools', async (tools) => {
+  // Delay utilities
+  await tools.delayFor(1000); // delay for 1000ms
+  await tools.delayForRandom(100, 500); // random delay between 100-500ms
+  
+  // Skip test conditionally
+  tools.skipIf(process.env.CI === 'true', 'Skipping in CI');
+  
+  // Skip test unconditionally
+  if (!apiKeyAvailable) {
+    tools.skip('API key not available');
+  }
+  
+  // Mark as todo
+  tools.todo('Needs implementation');
+  
+  // Retry configuration
+  tools.retry(3); // Set retry count
+  
+  // Timeout configuration
+  tools.timeout(10000); // Set timeout to 10s
+  
+  // Context sharing between tests
+  tools.context.set('userId', 12345);
+  const userId = tools.context.get('userId');
+  
+  // Deferred promises
+  const deferred = tools.defer();
+  setTimeout(() => deferred.resolve('done'), 100);
+  await deferred.promise;
+  
+  // Colored console output
+  const coloredString = await tools.coloredString('Success!', 'green');
+  console.log(coloredString);
+  
+  // Error handling helper
+  const error = await tools.returnError(async () => {
+    throw new Error('Expected error');
+  });
+  expect(error).toBeInstanceOf(Error);
+});
+```
+
+### Snapshot Testing
+
+```typescript
+tap.test('snapshot test', async (tools) => {
+  const output = generateComplexOutput();
+  
+  // Compare with saved snapshot
+  await tools.matchSnapshot(output);
+  
+  // Named snapshots for multiple checks in one test
+  await tools.matchSnapshot(output.header, 'header');
+  await tools.matchSnapshot(output.body, 'body');
+});
+
+// Update snapshots with: UPDATE_SNAPSHOTS=true tstest test/
+```
+
+### Test Fixtures
+
+```typescript
+// Define reusable fixtures
+tap.defineFixture('testUser', async (data) => ({
+  id: Date.now(),
+  name: data?.name || 'Test User',
+  email: data?.email || 'test@example.com',
+  created: new Date()
+}));
+
+tap.defineFixture('testPost', async (data) => ({
+  id: Date.now(),
+  title: data?.title || 'Test Post',
+  authorId: data?.authorId || 1
+}));
+
+// Use fixtures in tests
+tap.test('fixture test', async (tools) => {
+  const user = await tools.fixture('testUser', { name: 'John' });
+  const post = await tools.fixture('testPost', { authorId: user.id });
+  
+  expect(post.authorId).toEqual(user.id);
+  
+  // Factory pattern for multiple instances
+  const users = await tools.factory('testUser').createMany(5);
+  expect(users).toHaveLength(5);
+});
+```
+
+### Parallel Test Execution
+
+```typescript
+// Parallel tests within a file
+tap.testParallel('parallel test 1', async () => {
+  await heavyOperation();
+});
+
+tap.testParallel('parallel test 2', async () => {
+  await anotherHeavyOperation();
+});
+
+// File naming for parallel groups
+// test.api.para__1.ts - runs in parallel with other para__1 files
+// test.db.para__1.ts - runs in parallel with other para__1 files
+// test.auth.para__2.ts - runs after para__1 group completes
+```
+
+### Assertions with expect()
+
+tapbundle uses @push.rocks/smartexpect for assertions:
+
+```typescript
+// Basic assertions
+expect(value).toEqual(5);
+expect(value).not.toEqual(10);
+expect(obj).toDeepEqual({ a: 1, b: 2 });
+
+// Type assertions
+expect('hello').toBeTypeofString();
+expect(42).toBeTypeofNumber();
+expect(true).toBeTypeofBoolean();
+expect([]).toBeArray();
+expect({}).toBeTypeOf('object');
+
+// Comparison assertions
+expect(5).toBeGreaterThan(3);
+expect(3).toBeLessThan(5);
+expect(5).toBeGreaterThanOrEqual(5);
+expect(5).toBeLessThanOrEqual(5);
+expect(0.1 + 0.2).toBeCloseTo(0.3, 10);
+
+// Truthiness
+expect(true).toBeTrue();
+expect(false).toBeFalse();
+expect('text').toBeTruthy();
+expect(0).toBeFalsy();
+expect(null).toBeNull();
+expect(undefined).toBeUndefined();
+expect(null).toBeNullOrUndefined();
+
+// String assertions
+expect('hello world').toStartWith('hello');
+expect('hello world').toEndWith('world');
+expect('hello world').toInclude('lo wo');
+expect('hello world').toMatch(/^hello/);
+expect('option').toBeOneOf(['choice', 'option', 'alternative']);
+
+// Array assertions
+expect([1, 2, 3]).toContain(2);
+expect([1, 2, 3]).toContainAll([1, 3]);
+expect([1, 2, 3]).toExclude(4);
+expect([1, 2, 3]).toHaveLength(3);
+expect([]).toBeEmptyArray();
+expect([{ id: 1 }]).toContainEqual({ id: 1 });
+
+// Object assertions
+expect(obj).toHaveProperty('name');
+expect(obj).toHaveProperty('user.email', 'test@example.com');
+expect(obj).toHaveDeepProperty(['level1', 'level2']);
+expect(obj).toMatchObject({ name: 'John' });
+
+// Function assertions
+expect(() => { throw new Error('test'); }).toThrow();
+expect(() => { throw new Error('test'); }).toThrow(Error);
+expect(() => { throw new Error('test error'); }).toThrowErrorMatching(/test/);
+expect(myFunction).not.toThrow();
+
+// Promise assertions
+await expect(Promise.resolve('value')).resolves.toEqual('value');
+await expect(Promise.reject(new Error('fail'))).rejects.toThrow();
+
+// Custom assertions
+expect(7).customAssertion(
+  value => value % 2 === 1,
+  'Value is not odd'
+);
+```
+
+### Pre-tasks
+
+Run setup tasks before tests start:
+
+```typescript
+tap.preTask('setup database', async () => {
+  await initializeTestDatabase();
+  console.log('Database initialized');
+});
+
+tap.preTask('load environment', async () => {
+  await loadTestEnvironment();
+});
+
+// Pre-tasks run in order before any tests
+```
+
+### Tag-based Test Filtering
+
+```typescript
+// Tag individual tests
+tap.tags('unit', 'api')
+   .test('api unit test', async () => {
+     // Test code
+   });
+
+tap.tags('integration', 'slow')
+   .test('database integration', async () => {
+     // Test code
+   });
+
+// Run only tests with specific tags
+// tstest test/ --tags unit,api
+```
+
+### Context Sharing
+
+Share data between tests:
+
+```typescript
+tap.test('first test', async (tools) => {
+  const sessionId = await createSession();
+  tools.context.set('sessionId', sessionId);
+});
+
+tap.test('second test', async (tools) => {
+  const sessionId = tools.context.get('sessionId');
+  expect(sessionId).toBeDefined();
+  
+  // Cleanup
+  tools.context.delete('sessionId');
+});
+```
+
+### Browser Testing with webhelpers
+
+For browser-specific tests:
+
+```typescript
+import { tap, webhelpers } from '@git.zone/tstest/tapbundle';
+
+tap.test('DOM manipulation', async () => {
+  // Create DOM elements from HTML strings
+  const element = await webhelpers.fixture(webhelpers.html`
+    <div class="test-container">
+      <h1>Test Title</h1>
+      <button id="test-btn">Click Me</button>
+    </div>
+  `);
+  
+  expect(element.querySelector('h1').textContent).toEqual('Test Title');
+  
+  // Simulate interactions
+  const button = element.querySelector('#test-btn');
+  button.click();
+});
+
+tap.test('CSS testing', async () => {
+  const styles = webhelpers.css`
+    .test-class {
+      color: red;
+      font-size: 16px;
+    }
+  `;
+  
+  // styles is a string that can be injected into the page
+  expect(styles).toInclude('color: red');
+});
+```
+
+### Advanced Error Handling
+
+```typescript
+tap.test('error handling', async (tools) => {
+  // Capture errors without failing the test
+  const error = await tools.returnError(async () => {
+    await functionThatThrows();
+  });
+  
+  expect(error).toBeInstanceOf(Error);
+  expect(error.message).toEqual('Expected error message');
+});
+```
+
+### Test Wrap
+
+Create wrapped test environments:
+
+```typescript
+import { TapWrap } from '@git.zone/tstest/tapbundle';
+
+const tapWrap = new TapWrap({
+  before: async () => {
+    console.log('Before all tests');
+    await globalSetup();
+  },
+  after: async () => {
+    console.log('After all tests');
+    await globalCleanup();
+  }
+});
+
+// Tests registered here will have the wrap lifecycle
+tapWrap.tap.test('wrapped test', async () => {
+  // This test runs with the wrap setup/teardown
+});
+```
+
+## Advanced Features
+
+### Glob Pattern Support
+
+Run specific test patterns:
+```bash
+# Run all unit tests
+tstest "test/unit/**/*.ts"
+
+# Run all integration tests
+tstest "test/integration/*.test.ts"
+
+# Run multiple patterns
+tstest "test/**/*.spec.ts" "test/**/*.test.ts"
+```
+
+**Important**: Always quote glob patterns to prevent shell expansion. Without quotes, the shell will expand the pattern and only pass the first matching file to tstest.
+
+### Enhanced Test Logging
+
+The `--logfile` option provides intelligent test logging with automatic organization:
+
+```bash
+tstest test/ --logfile
+```
+
+**Log Organization:**
+- **Current Run**: `.nogit/testlogs/[testname].log`
+- **Previous Run**: `.nogit/testlogs/previous/[testname].log`
+- **Failed Tests**: `.nogit/testlogs/00err/[testname].log`
+- **Changed Output**: `.nogit/testlogs/00diff/[testname].log`
+
+**Features:**
+- Previous logs are automatically moved to the `previous/` folder
+- Failed tests create copies in `00err/` for quick identification
+- Tests with changed output create diff reports in `00diff/`
+- The `00err/` and `00diff/` folders are cleared on each run
+
+**Example Diff Report:**
+```
+DIFF REPORT: test__api__integration.log
+Generated: 2025-05-24T01:29:13.847Z
+================================================================================
+
+- [Line 8]    ✅ api test passes (150ms)
+ [Line 8]    ✅ api test passes (165ms)
+
+================================================================================
+Previous version had 40 lines
+Current version has 40 lines
+```
+
+### Test Timeout Protection
+
+Prevent runaway tests with the `--timeout` option:
+
+```bash
+# Timeout any test file that runs longer than 60 seconds
+tstest test/ --timeout 60
+
+# Shorter timeout for unit tests
+tstest test/unit/ --timeout 10
+```
+
+When a test exceeds the timeout:
+- The test process is terminated (SIGTERM)
+- The test is marked as failed
+- An error log is created in `.nogit/testlogs/00err/`
+- Clear error message shows the timeout duration
+
+### Test File Range Control
+
+Run specific ranges of test files using `--startFrom` and `--stopAt`:
+
+```bash
+# Run tests starting from the 5th file
+tstest test/ --startFrom 5
+
+# Run only files 5 through 10
+tstest test/ --startFrom 5 --stopAt 10
+
+# Run only the first 3 test files
+tstest test/ --stopAt 3
+```
+
+This is particularly useful for:
+- Debugging specific test failures in large test suites
+- Running tests in chunks on different CI runners
+- Quickly testing changes to specific test files
+
+The output shows which files are skipped:
+```
+⏭️  test/auth.test.ts (1/10)
+   Skipped: before start range (5)
+⏭️  test/user.test.ts (2/10)
+   Skipped: before start range (5)
+▶️  test/api.test.ts (5/10)
+   Runtime: node.js
+   ✅ api endpoints work (145ms)
+```
+
+### Performance Analysis
+
+In verbose mode, see performance metrics:
+```
+⏱️  Performance Metrics:
+   Average per test: 135ms
+   Slowest test: api integration test (486ms)
+```
+
+### Parallel Test Groups
+
+Tests can be organized into parallel groups for concurrent execution:
+
+```
+━━━ Parallel Group: para__1 ━━━
+▶️  test/auth.para__1.ts
+▶️  test/user.para__1.ts
+   ... tests run concurrently ...
+──────────────────────────────────
+
+━━━ Parallel Group: para__2 ━━━
+▶️  test/db.para__2.ts
+▶️  test/api.para__2.ts
+   ... tests run concurrently ...
+──────────────────────────────────
+```
+
+Files with the same parallel group suffix (e.g., `para__1`) run simultaneously, while different groups run sequentially.
+
+### CI/CD Integration
+
+For continuous integration, combine quiet and JSON modes:
+```bash
+# GitHub Actions example
+tstest test/ --json > test-results.json
+
+# Or minimal output
+tstest test/ --quiet
+```
+
+**Advanced CI Example:**
+```bash
+# Run tests with comprehensive logging and safety features
+tstest test/ \
+  --timeout 300 \
+  --logfile \
+  --json > test-results.json
+
+# Run specific test chunks in parallel CI jobs
+tstest test/ --startFrom 1 --stopAt 10   # Job 1
+tstest test/ --startFrom 11 --stopAt 20  # Job 2
+tstest test/ --startFrom 21              # Job 3
+```
+
+### Debugging Failed Tests
+
+When tests fail, use the enhanced logging features:
+
+```bash
+# Run with logging to capture detailed output
+tstest test/ --logfile --verbose
+
+# Check error logs
+ls .nogit/testlogs/00err/
+
+# Review diffs for flaky tests
+cat .nogit/testlogs/00diff/test__api__endpoints.log
+
+# Re-run specific failed tests
+tstest test/api/endpoints.test.ts --verbose --timeout 60
+```
+
+## Changelog
+
+### Version 1.10.0
+- ⏱️ Added `--timeout <seconds>` option for test file timeout protection
+- 🎯 Added `--startFrom <n>` and `--stopAt <n>` options for test file range control
+- 📁 Enhanced `--logfile` with intelligent log organization:
+  - Previous logs moved to `previous/` folder
+  - Failed tests copied to `00err/` folder
+  - Changed tests create diff reports in `00diff/` folder
+- 🔍 Improved test discovery to show skipped files with clear reasons
+- 🐛 Fixed TypeScript compilation warnings and unused variables
+- 📊 Test summaries now include skipped file counts
+
+### Version 1.9.2
+- 🐛 Fixed test timing display issue (removed duplicate timing in output)
+- 📝 Improved internal protocol design documentation
+- 🔧 Added protocol v2 utilities for future improvements
+
+### Version 1.9.1  
+- 🐛 Fixed log file naming to preserve directory structure
+- 📁 Log files now prevent collisions: `test__dir__file.log`
+
+### Version 1.9.0
+- 📚 Comprehensive documentation update
+- 🏗️ Embedded tapbundle for better integration
+- 🌐 Full browser compatibility
+
+### Version 1.8.0
+- 📦 Embedded tapbundle directly into tstest project
+- 🌐 Made tapbundle fully browser-compatible
+- 📸 Added snapshot testing with base64-encoded communication protocol
+- 🏷️ Introduced tag-based test filtering
+- 🔧 Enhanced test lifecycle hooks (beforeEach/afterEach)
+- 🎯 Fixed parallel test execution and grouping
+- ⏳ Improved timeout and retry mechanisms
+- 🛠️ Added test fixtures for reusable test data
+- 📊 Enhanced TAP parser for better test reporting
+- 🐛 Fixed glob pattern handling in shell scripts
+
+## License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license.md) file within this repository. 
+
+**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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH  
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require 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.
--- a/readme.plan.md
+++ b/readme.plan.md
@ -1,199 +1,232 @@
-# Plan for improving logging and output in tstest
+# Improvement Plan for tstest and tapbundle

 !! FIRST: Reread /home/philkunz/.claude/CLAUDE.md to ensure following all guidelines !!

-## Goal - ✅ MOSTLY COMPLETED
- ✅ Make test output cleaner and more visually appealing
- ✅ Add structured logging capabilities
- ✅ Support different verbosity levels
- ✅ Improve CI/CD compatibility
- ✅ Add progress indicators and timing summaries
+## Improved Internal Protocol (NEW - Critical)

-## Current State - UPDATED
- ✅ Clean, modern visual design with Unicode characters
- ✅ Structured output format (JSON support)
- ✅ Multiple verbosity levels (quiet, normal, verbose)
- ✅ Real-time output with cleaner formatting
- ✅ Better error aggregation and display
- ✅ TAP protocol support integrated with new logger
+### 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

-## Completed Improvements
+### 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

-### 1. ✅ Created new TsTestLogger class
- ✅ Centralized logging with consistent formatting
- ✅ Support for different output modes (normal, quiet, verbose)
- ✅ Better visual hierarchy with modern Unicode characters
- ✅ Progress indicators for multiple test files
- ✅ Structured error collection and display
+### 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

-### 2. ✅ Updated visual design
- ✅ Replaced heavy separators with cleaner alternatives
- ✅ Used better emoji and Unicode characters
- ✅ Added indentation for hierarchical display
- ✅ Grouped related information visually
- ✅ Added color coding consistently
+See `readme.protocol.md` for detailed specification.

-### 3. ✅ Added command-line options
- ✅ `--quiet` for minimal CI-friendly output
- ✅ `--verbose` for detailed debugging information
- ✅ `--no-color` for environments without color support
- ✅ `--json` for structured JSON output
- ⏳ `--log-file <path>` for persistent logging (TODO)
+## Test Configuration System (NEW)

-### 4. ✅ Improved progress feedback
- ⏳ Show progress bar for multiple files (TODO)
- ✅ Display current file being executed
- ✅ Show real-time test counts
- ⏳ Add ETA for long test suites (TODO)
+### 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

-### 5. ✅ Better error and summary display
- ✅ Collect all errors and display at end
- ✅ Show timing metrics and performance summary (in verbose mode)
- ✅ Highlight slowest tests (in verbose mode)
- ✅ Add test failure context
-
-### 6. ✅ Browser console integration
- ✅ Clearly separate browser logs from test output
- ⏳ Add browser log filtering options (TODO)
- ✅ Format browser errors specially
-
-## Implementation Steps - COMPLETED
-
-### Phase 1: ✅ Core Logger Implementation
-1. ✅ Created `tstest.logging.ts` with TsTestLogger class
-2. ✅ Added LogOptions interface for configuration
-3. ✅ Implemented basic formatting methods
-4. ✅ Added progress and summary methods
-
-### Phase 2: ✅ Integration
-1. ✅ Updated CLI to accept new command-line options
-2. ✅ Modified TsTest class to use new logger
-3. ✅ Updated TapParser to use structured logging
-4. ✅ Updated TapCombinator for better summaries
-
-### Phase 3: ✅ Visual Improvements
-1. ✅ Replaced all existing separators
-2. ✅ Updated color scheme
-3. ✅ Added emoji and Unicode characters
-4. ✅ Implemented hierarchical output
-
-### Phase 4: ✅ Advanced Features
-1. ✅ Add JSON output format
-2. ⏳ Implement file-based logging (TODO)
-3. ✅ Add performance metrics collection
-4. ✅ Create error aggregation system
-
-### Phase 5: ✅ Browser Integration
-1. ✅ Update browser console forwarding
-2. ✅ Add browser log formatting
-3. ✅ Implement browser-specific indicators
-
-## Files modified
- ✅ `ts/tstest.logging.ts` - New logger implementation (created)
- ✅ `ts/index.ts` - Added CLI options parsing
- ✅ `ts/tstest.classes.tstest.ts` - Integrated new logger
- ✅ `ts/tstest.classes.tap.parser.ts` - Updated output formatting
- ✅ `ts/tstest.classes.tap.combinator.ts` - Improved summary display
- ❌ `ts/tstest.logprefixes.ts` - Still in use, can be deprecated later
- ❌ `package.json` - No new dependencies needed
-
-## Success Criteria - ACHIEVED
- ✅ Cleaner, more readable test output
- ✅ Configurable verbosity levels
- ✅ Better CI/CD integration
- ✅ Improved error visibility
- ✅ Performance metrics available
- ✅ Consistent visual design
- ✅ Maintained backward compatibility
-
-## Example Output Comparison
-
-### Current Output
-```
-☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰☰
-**TSTEST** FOUND 4 TESTFILE(S):
-**TSTEST** test/test.ts
------------------------------------------------
-=> Running test/test.ts in node.js runtime.
-= = = = = = = = = = = = = = = = = = = = = = = =
+### 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
+}
 ```

-### Actual Output (IMPLEMENTED)
-```
-🔍 Test Discovery
-   Mode: directory
-   Pattern: test
-   Found: 4 test file(s)
+### Settings Inheritance
+- Global (00init.ts) → File level → Test level
+- More specific settings override less specific ones
+- Arrays/objects are merged, primitives are replaced

-▶️  test/test.ts (1/4)
-   Runtime: node.js
-   ✅ prepare test (0ms)
-   Summary: 1/1 PASSED
+### 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

-▶️  test/test.single.ts (2/4)
-   Runtime: node.js
-   ✅ single file test execution (1ms)
-   Summary: 1/1 PASSED
+## 1. Enhanced Communication Between tapbundle and tstest

-📊 Test Summary
-┌────────────────────────────────┐
-│ Total Files:                 4 │
-│ Total Tests:                 4 │
-│ Passed:                      4 │
-│ Failed:                      0 │
-│ Duration:                 5739ms │
-└────────────────────────────────┘
+### 1.1 Real-time Test Progress API
+- Create a bidirectional communication channel between tapbundle and tstest
+- Emit events for test lifecycle stages (start, progress, completion)
+- Allow tstest to subscribe to tapbundle events for better progress reporting
+- Implement a standardized message format for test metadata

-ALL TESTS PASSED! 🎉
+### 1.2 Rich Error Reporting
+- Pass structured error objects from tapbundle to tstest
+- Include stack traces, code snippets, and contextual information
+- Support for error categorization (assertion failures, timeouts, uncaught exceptions)
+- Visual diff output for failed assertions
+
+## 2. Enhanced toolsArg Functionality
+
+### 2.3 Test Data and Context Sharing (Partial)
+```typescript
+tap.test('data-driven test', async (toolsArg) => {
+  // Parameterized test data (not yet implemented)
+  const testData = toolsArg.data<TestInput>();
+  expect(processData(testData)).toEqual(expected);
+});
 ```

-### Additional Features Implemented
+## 3. Nested Tests and Test Suites

-1. **Quiet Mode**:
-```
-Found 1 tests
-✅ single file test execution
+### 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
+- Suite-level lifecycle hooks

-Summary: 1/1 | 1210ms | PASSED
+## 4. Advanced Test Features
+
+### 4.1 Snapshot Testing ✅ (Basic implementation complete)
+
+### 4.2 Performance Benchmarking
+```typescript
+tap.test('performance test', async (toolsArg) => {
+  const benchmark = toolsArg.benchmark();
+  
+  // Run operation
+  await expensiveOperation();
+  
+  // Assert performance constraints
+  benchmark.expect({
+    maxDuration: 1000,
+    maxMemory: '100MB'
+  });
+});
 ```

-2. **JSON Mode**:
-```json
-{"event":"discovery","count":1,"pattern":"test/test.single.ts","executionMode":"file"}
-{"event":"fileStart","filename":"test/test.single.ts","runtime":"node.js","index":1,"total":1}
-{"event":"testResult","testName":"single file test execution","passed":true,"duration":0}
-{"event":"summary","summary":{"totalFiles":1,"totalTests":1,"totalPassed":1,"totalFailed":0,"totalDuration":1223,"fileResults":[...]}}
+
+## 5. Test Execution Improvements
+
+
+### 5.2 Watch Mode
+- Automatically re-run tests on file changes
+- Intelligent test selection based on changed files
+- Fast feedback loop for development
+- Integration with IDE/editor plugins
+
+### 5.3 Advanced Test Filtering (Partial)
+```typescript
+// Exclude tests by pattern (not yet implemented)
+tstest --exclude "**/slow/**"
+
+// Run only failed tests from last run (not yet implemented)
+tstest --failed
+
+// Run tests modified in git (not yet implemented)
+tstest --changed
 ```

-3. **Error Display**:
-```
-❌ Failed Tests:
+## 6. Reporting and Analytics

-   test/test.fail.ts
-      ❌ This test should fail
+### 6.1 Custom Reporters
+- Plugin architecture for custom reporters
+- Built-in reporters: JSON, JUnit, HTML, Markdown
+- Real-time streaming reporters
+- Aggregated test metrics and trends

-SOME TESTS FAILED! ❌
-```
+### 6.2 Coverage Integration
+- Built-in code coverage collection
+- Coverage thresholds and enforcement
+- Coverage trending over time
+- Integration with CI/CD pipelines

-## Summary of Implementation
+### 6.3 Test Analytics Dashboard
+- Web-based dashboard for test results
+- Historical test performance data
+- Flaky test detection
+- Test impact analysis

-The logging improvement plan has been successfully implemented with the following achievements:
+## 7. Developer Experience

-1. **Created a new centralized TsTestLogger class** that handles all output formatting
-2. **Added multiple output modes**: quiet, normal, verbose, and JSON
-3. **Improved visual design** with modern Unicode characters and emojis
-4. **Added CLI argument parsing** for all new options
-5. **Integrated the logger throughout the codebase** (TsTest, TapParser, TapCombinator)
-6. **Better error aggregation and display** with failed tests shown at the end
-7. **Performance metrics** available in verbose mode
-8. **Clean, hierarchical output** that's much more readable
+### 7.1 Better Error Messages
+- Clear, actionable error messages
+- Suggestions for common issues
+- Links to documentation
+- Code examples in error output

-### Remaining TODOs
+## Implementation Phases

-Only a few minor features remain unimplemented:
- File-based logging (--log-file option)
- Progress bar visualization
- ETA for long test suites
- Browser log filtering options
+### 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

-The core logging improvements are complete and provide a much better user experience!
+### 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 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 4: Developer Experience (Priority: Medium)
+1. Add watch mode
+2. Implement custom reporters
+3. Complete advanced test filtering options
+4. Add performance benchmarking API
+
+### Phase 5: Analytics and Performance (Priority: Low)
+1. Build test analytics dashboard
+2. Implement coverage integration
+3. Create trend analysis tools
+4. Add test impact analysis
+
+## Technical Considerations
+
+### API Design Principles
+- Maintain backward compatibility
+- Progressive enhancement approach
+- Opt-in features to avoid breaking changes
+- Clear migration paths for new features
+
+### Performance Goals
+- Minimal overhead for test execution
+- Efficient parallel execution
+- Fast test discovery
+- Optimized browser test bundling
+
+### Integration Points
+- Clean interfaces between tstest and tapbundle
+- Extensible plugin architecture
+- Standard test result format
+- Compatible with existing CI/CD tools
--- a/readme.protocol.md
+++ b/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
--- a/test/debug.js
+++ b/test/debug.js
@ -0,0 +1,3 @@
+// Direct run to see TAP output
+const { execSync } = require('child_process');
+console.log(execSync('tsx test/tapbundle/test.debug.ts', { cwd: '/mnt/data/lossless/git.zone/tstest' }).toString());
--- a/test/glob-test/another.spec.ts
+++ b/test/glob-test/another.spec.ts
@ -0,0 +1,8 @@
+import { tap } from '../../ts_tapbundle/index.js';
+
+tap.test('spec file test', async () => {
+  console.log('This is a .spec.ts file that should be found by glob');
+  return true;
+});
+
+tap.start();
--- a/test/glob-test/nested/test.nested-glob.ts
+++ b/test/glob-test/nested/test.nested-glob.ts
@ -0,0 +1,8 @@
+import { tap } from '../../../ts_tapbundle/index.js';
+
+tap.test('nested glob pattern test', async () => {
+  console.log('This test file is in a nested directory');
+  return true;
+});
+
+tap.start();
--- a/test/glob-test/test.glob-test.ts
+++ b/test/glob-test/test.glob-test.ts
@ -0,0 +1,8 @@
+import { tap } from '../../ts_tapbundle/index.js';
+
+tap.test('glob pattern test', async () => {
+  console.log('This test file should be found by glob patterns');
+  return true;
+});
+
+tap.start();
--- a/test/tapbundle/test.browser.nonci.ts
+++ b/test/tapbundle/test.browser.nonci.ts
@ -0,0 +1,55 @@
+import { tap, expect, webhelpers } from '../../ts_tapbundle/index.js';
+
+tap.preTask('custompretask', async () => {
+  console.log('this is a pretask');
+});
+
+tap.test('should have access to webhelpers', async () => {
+  const myElement = await webhelpers.fixture(webhelpers.html`<div></div>`);
+  expect(myElement).toBeInstanceOf(HTMLElement);
+  console.log(myElement);
+});
+
+const test1 = tap.test('my first test -> expect true to be true', async () => {
+  return expect(true).toBeTrue();
+});
+
+const test2 = tap.test('my second test', async (tools) => {
+  await tools.delayFor(50);
+});
+
+const test3 = tap.test(
+  'my third test -> test2 should take longer than test1 and endure at least 1000ms',
+  async () => {
+    expect(
+      (await test1.testPromise).hrtMeasurement.milliSeconds <
+        (await test2).hrtMeasurement.milliSeconds,
+    ).toBeTrue();
+    expect((await test2.testPromise).hrtMeasurement.milliSeconds > 10).toBeTrue();
+  },
+);
+
+const test4 = tap.skip.test('my 4th test -> should fail', async (tools) => {
+  tools.allowFailure();
+  expect(false).toBeTrue();
+});
+
+const test5 = tap.test('my 5th test -> should pass in about 500ms', async (tools) => {
+  tools.timeout(1000);
+  await tools.delayFor(500);
+});
+
+const test6 = tap.skip.test('my 6th test -> should fail after 1000ms', async (tools) => {
+  tools.allowFailure();
+  tools.timeout(1000);
+  await tools.delayFor(100);
+});
+
+const testPromise = tap.start();
+
+// Export promise for browser compatibility
+if (typeof globalThis !== 'undefined') {
+  (globalThis as any).tapPromise = testPromise;
+}
+
+export default testPromise;
--- a/test/tapbundle/test.debug.ts
+++ b/test/tapbundle/test.debug.ts
@ -0,0 +1,19 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// Simple test to debug TAP output
+tap.test('test 1', async () => {
+  console.log('Test 1 running');
+  expect(true).toBeTrue();
+});
+
+tap.test('test 2 - skip', async (toolsArg) => {
+  toolsArg.skip('Skipping test 2');
+  expect(false).toBeTrue();
+});
+
+tap.test('test 3', async () => {
+  console.log('Test 3 running');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tapbundle/test.describe.ts
+++ b/test/tapbundle/test.describe.ts
@ -0,0 +1,101 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// Global state for testing lifecycle hooks
+const lifecycleOrder: string[] = [];
+
+tap.describe('Test Suite A', () => {
+  tap.beforeEach(async (toolsArg) => {
+    lifecycleOrder.push('Suite A - beforeEach');
+  });
+  
+  tap.afterEach(async (toolsArg) => {
+    lifecycleOrder.push('Suite A - afterEach');
+  });
+  
+  tap.test('test 1 in suite A', async (toolsArg) => {
+    lifecycleOrder.push('Test 1');
+    expect(true).toBeTrue();
+  });
+  
+  tap.test('test 2 in suite A', async (toolsArg) => {
+    lifecycleOrder.push('Test 2');
+    expect(true).toBeTrue();
+  });
+  
+  tap.describe('Nested Suite B', () => {
+    tap.beforeEach(async (toolsArg) => {
+      lifecycleOrder.push('Suite B - beforeEach');
+    });
+    
+    tap.afterEach(async (toolsArg) => {
+      lifecycleOrder.push('Suite B - afterEach');
+    });
+    
+    tap.test('test 1 in nested suite B', async (toolsArg) => {
+      lifecycleOrder.push('Nested Test 1');
+      expect(true).toBeTrue();
+    });
+  });
+});
+
+// Test outside any suite
+tap.test('test outside suites', async (toolsArg) => {
+  lifecycleOrder.push('Outside Test');
+  expect(true).toBeTrue();
+});
+
+tap.describe('Test Suite with errors', () => {
+  tap.beforeEach(async (toolsArg) => {
+    // Setup that might fail
+    const data = await Promise.resolve({ value: 42 });
+    toolsArg.testData = data;
+  });
+  
+  tap.test('test with error', async (toolsArg) => {
+    // Verify that data from beforeEach is available
+    expect(toolsArg.testData).toBeDefined();
+    expect(toolsArg.testData.value).toEqual(42);
+    
+    // Test that error handling works by catching an error
+    try {
+      throw new Error('Intentional error');
+    } catch (error) {
+      expect(error.message).toEqual('Intentional error');
+    }
+  });
+  
+  tap.test('test with skip in suite', async (toolsArg) => {
+    toolsArg.skip('Skipping this test in a suite');
+    expect(false).toBeTrue();
+  });
+});
+
+// Verify lifecycle order - this test runs last to check if all hooks were called properly
+tap.test('verify lifecycle hook order', async (toolsArg) => {
+  // Wait a bit to ensure all tests have completed
+  await new Promise(resolve => setTimeout(resolve, 50));
+  console.log('Lifecycle order:', lifecycleOrder);
+  
+  // Check that the tests we expect to have run actually did
+  expect(lifecycleOrder).toContain('Test 1');
+  expect(lifecycleOrder).toContain('Test 2');
+  expect(lifecycleOrder).toContain('Nested Test 1');
+  
+  // Check that beforeEach was called before each test in Suite A
+  const test1Index = lifecycleOrder.indexOf('Test 1');
+  expect(test1Index).toBeGreaterThan(-1);
+  const beforeTest1 = lifecycleOrder.slice(0, test1Index);
+  expect(beforeTest1).toContain('Suite A - beforeEach');
+  
+  // Check that afterEach was called after test 1
+  const afterTest1 = lifecycleOrder.slice(test1Index + 1);
+  expect(afterTest1).toContain('Suite A - afterEach');
+  
+  // Check nested suite lifecycle
+  const nestedTest1Index = lifecycleOrder.indexOf('Nested Test 1');
+  expect(nestedTest1Index).toBeGreaterThan(-1);
+  const beforeNestedTest1 = lifecycleOrder.slice(0, nestedTest1Index);
+  expect(beforeNestedTest1).toContain('Suite B - beforeEach');
+});
+
+tap.start();
--- a/test/tapbundle/test.fixtures.ts
+++ b/test/tapbundle/test.fixtures.ts
@ -0,0 +1,120 @@
+import { tap, TapTools } from '../../ts_tapbundle/index.js';
+import { expect } from '@push.rocks/smartexpect';
+
+// Define fixture factories
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+}
+
+interface Post {
+  id: number;
+  title: string;
+  content: string;
+  authorId: number;
+  tags: string[];
+}
+
+// Define user fixture factory
+TapTools.defineFixture<User>('user', (data) => {
+  const id = data?.id || Math.floor(Math.random() * 10000);
+  return {
+    id,
+    name: data?.name || `Test User ${id}`,
+    email: data?.email || `user${id}@test.com`,
+    role: data?.role || 'user'
+  };
+});
+
+// Define post fixture factory
+TapTools.defineFixture<Post>('post', async (data) => {
+  const id = data?.id || Math.floor(Math.random() * 10000);
+  return {
+    id,
+    title: data?.title || `Post ${id}`,
+    content: data?.content || `Content for post ${id}`,
+    authorId: data?.authorId || 1,
+    tags: data?.tags || ['test', 'sample']
+  };
+});
+
+tap.describe('Fixture System', () => {
+  tap.afterEach(async () => {
+    // Clean up fixtures after each test
+    await TapTools.cleanupFixtures();
+  });
+
+  tap.tags('unit', 'fixtures')
+    .test('should create a simple fixture', async (toolsArg) => {
+      const user = await toolsArg.fixture<User>('user');
+      
+      expect(user).toHaveProperty('id');
+      expect(user).toHaveProperty('name');
+      expect(user).toHaveProperty('email');
+      expect(user.role).toEqual('user');
+    });
+
+  tap.tags('unit', 'fixtures')
+    .test('should create fixture with custom data', async (toolsArg) => {
+      const admin = await toolsArg.fixture<User>('user', {
+        name: 'Admin User',
+        role: 'admin'
+      });
+      
+      expect(admin.name).toEqual('Admin User');
+      expect(admin.role).toEqual('admin');
+      expect(admin.email).toContain('@test.com');
+    });
+
+  tap.tags('unit', 'fixtures')
+    .test('should create multiple fixtures with factory', async (toolsArg) => {
+      const userFactory = toolsArg.factory<User>('user');
+      const users = await userFactory.createMany(3);
+      
+      // Try different approach
+      expect(users.length).toEqual(3);
+      expect(users[0].id).not.toEqual(users[1].id);
+      expect(users[0].email).not.toEqual(users[1].email);
+    });
+
+  tap.tags('unit', 'fixtures')
+    .test('should create fixtures with custom data per instance', async (toolsArg) => {
+      const postFactory = toolsArg.factory<Post>('post');
+      const posts = await postFactory.createMany(3, (index) => ({
+        title: `Post ${index + 1}`,
+        tags: [`tag${index + 1}`]
+      }));
+      
+      expect(posts[0].title).toEqual('Post 1');
+      expect(posts[1].title).toEqual('Post 2');
+      expect(posts[2].title).toEqual('Post 3');
+      
+      expect(posts[0].tags).toContain('tag1');
+      expect(posts[1].tags).toContain('tag2');
+    });
+
+  tap.tags('unit', 'fixtures')
+    .test('should handle related fixtures', async (toolsArg) => {
+      const user = await toolsArg.fixture<User>('user', { name: 'Author' });
+      const post = await toolsArg.fixture<Post>('post', {
+        title: 'My Article',
+        authorId: user.id
+      });
+      
+      expect(post.authorId).toEqual(user.id);
+    });
+
+  tap.tags('unit', 'fixtures', 'error')
+    .test('should throw error for undefined fixture', async (toolsArg) => {
+      try {
+        await toolsArg.fixture('nonexistent');
+        expect(true).toBeFalse(); // Should not reach here
+      } catch (error: any) {
+        expect(error.message).toContain('Fixture \'nonexistent\' not found');
+      }
+    });
+});
+
+tap.start();
--- a/test/tapbundle/test.fluent-syntax.ts
+++ b/test/tapbundle/test.fluent-syntax.ts
@ -0,0 +1,32 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// Test with fluent syntax
+tap.tags('unit', 'fluent')
+  .priority('high')
+  .test('test with fluent syntax', async (toolsArg) => {
+    expect(true).toBeTrue();
+    toolsArg.context.set('fluentTest', 'works');
+  });
+
+// Chain multiple settings
+tap.tags('integration')
+  .priority('low')
+  .retry(3)
+  .timeout(5000)
+  .test('test with multiple settings', async (toolsArg) => {
+    expect(true).toBeTrue();
+  });
+
+// Test context access from fluent test
+tap.tags('unit')
+  .test('verify fluent context', async (toolsArg) => {
+    const fluentValue = toolsArg.context.get('fluentTest');
+    expect(fluentValue).toEqual('works');
+  });
+
+// Test without tags - should show all tests run without filtering
+tap.test('regular test without tags', async (toolsArg) => {
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tapbundle/test.node.ts
+++ b/test/tapbundle/test.node.ts
@ -0,0 +1,28 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+import { tapNodeTools } from '../../ts_tapbundle_node/index.js';
+
+tap.test('should execure a command', async () => {
+  const result = await tapNodeTools.runCommand('ls -la');
+  expect(result.exitCode).toEqual(0);
+});
+
+tap.test('should create a https cert', async () => {
+  const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
+  console.log(key);
+  console.log(cert);
+  expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----');
+  expect(cert).toInclude('-----BEGIN CERTIFICATE-----');
+});
+
+tap.test('should create a smartmongo instance', async () => {
+  const smartmongo = await tapNodeTools.createSmartmongo();
+  await smartmongo.stop();
+});
+
+tap.test('should create a smarts3 instance', async () => {
+  const smarts3 = await tapNodeTools.createSmarts3();
+  await smarts3.stop();
+});
+
+tap.start();
--- a/test/tapbundle/test.snapshot.ts
+++ b/test/tapbundle/test.snapshot.ts
@ -0,0 +1,52 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// Test basic snapshot functionality
+tap.tags('unit', 'snapshot')
+  .test('should match string snapshot', async (toolsArg) => {
+    const testString = 'Hello, World!';
+    await toolsArg.matchSnapshot(testString);
+  });
+
+// Test object snapshot
+tap.tags('unit', 'snapshot')
+  .test('should match object snapshot', async (toolsArg) => {
+    const testObject = {
+      name: 'Test User',
+      age: 30,
+      hobbies: ['reading', 'coding', 'gaming'],
+      metadata: {
+        created: '2024-01-01',
+        updated: '2024-01-15'
+      }
+    };
+    await toolsArg.matchSnapshot(testObject);
+  });
+
+// Test named snapshots
+tap.tags('unit', 'snapshot')
+  .test('should handle multiple named snapshots', async (toolsArg) => {
+    const config1 = { version: '1.0.0', features: ['a', 'b'] };
+    const config2 = { version: '2.0.0', features: ['a', 'b', 'c'] };
+    
+    await toolsArg.matchSnapshot(config1, 'config_v1');
+    await toolsArg.matchSnapshot(config2, 'config_v2');
+  });
+
+// Test dynamic content with snapshot
+tap.tags('unit', 'snapshot')
+  .test('should handle template snapshot', async (toolsArg) => {
+    const template = `
+      <div class="container">
+        <h1>Welcome</h1>
+        <p>This is a test template</p>
+        <ul>
+          <li>Item 1</li>
+          <li>Item 2</li>
+        </ul>
+      </div>
+    `.trim();
+    
+    await toolsArg.matchSnapshot(template, 'html_template');
+  });
+
+tap.start();
--- a/test/tapbundle/test.tags-context.ts
+++ b/test/tapbundle/test.tags-context.ts
@ -0,0 +1,49 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// First test sets some data and has tags
+tap.tags('unit', 'context')
+  .priority('high')
+  .test('test with tags and context setting', async (toolsArg) => {
+    // Set some data in context
+    toolsArg.context.set('testData', { value: 42 });
+    toolsArg.context.set('users', ['alice', 'bob']);
+    
+    expect(true).toBeTrue();
+  });
+
+// Second test reads the context data
+tap.tags('unit', 'context')
+  .test('test reading context', async (toolsArg) => {
+    // Read data from context
+    const testData = toolsArg.context.get('testData');
+    const users = toolsArg.context.get('users');
+    
+    expect(testData).toEqual({ value: 42 });
+    expect(users).toContain('alice');
+    expect(users).toContain('bob');
+  });
+
+// Test without tags - should be skipped when filtering by tags
+tap.test('test without tags', async (toolsArg) => {
+  expect(true).toBeTrue();
+});
+
+// Test with different tags
+tap.tags('integration')
+  .priority('low')
+  .test('integration test', async (toolsArg) => {
+    expect(true).toBeTrue();
+  });
+
+// Test context cleanup
+tap.tags('unit')
+  .test('test context operations', async (toolsArg) => {
+    // Set and delete
+    toolsArg.context.set('temp', 'value');
+    expect(toolsArg.context.get('temp')).toEqual('value');
+    
+    toolsArg.context.delete('temp');
+    expect(toolsArg.context.get('temp')).toBeUndefined();
+  });
+
+tap.start();
--- a/test/tapbundle/test.tapwrap.ts
+++ b/test/tapbundle/test.tapwrap.ts
@ -0,0 +1,5 @@
+import { tap, expect, TapWrap } from '../../ts_tapbundle/index.js';
+
+tap.test('should run a test', async () => {});
+
+tap.start();
--- a/test/tapbundle/test.toolsarg.ts
+++ b/test/tapbundle/test.toolsarg.ts
@ -0,0 +1,85 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// Test skip functionality
+tap.test('should skip a test with skip()', async (toolsArg) => {
+  toolsArg.skip('This test is skipped');
+  // This code should not run
+  expect(false).toBeTrue();
+});
+
+tap.test('should conditionally skip with skipIf()', async (toolsArg) => {
+  const shouldSkip = true;
+  toolsArg.skipIf(shouldSkip, 'Condition met, skipping');
+  // This code should not run
+  expect(false).toBeTrue();
+});
+
+tap.test('should not skip when skipIf condition is false', async (toolsArg) => {
+  const shouldSkip = false;
+  toolsArg.skipIf(shouldSkip, 'Should not skip');
+  // This code should run
+  expect(true).toBeTrue();
+});
+
+// Test todo functionality
+tap.test('should mark test as todo', async (toolsArg) => {
+  toolsArg.todo('Not implemented yet');
+  // Test code that would be implemented later
+  expect(true).toBeTrue();
+});
+
+// Test timeout functionality
+tap.test('should set custom timeout', async (toolsArg) => {
+  toolsArg.timeout(5000);
+  // Simulate a task that takes 100ms
+  await toolsArg.delayFor(100);
+  expect(true).toBeTrue();
+});
+
+// This test is expected to fail due to timeout
+tap.test('should timeout when exceeding limit', async (toolsArg) => {
+  toolsArg.timeout(100);
+  // This test will timeout and be marked as failed by the test runner
+  await toolsArg.delayFor(2000);
+  // This line should not be reached due to timeout
+});
+
+tap.test('timeout should work properly', async (toolsArg) => {
+  toolsArg.timeout(200);
+  // This test should complete successfully within the timeout
+  await toolsArg.delayFor(50);
+  expect(true).toBeTrue();
+});
+
+// Test retry functionality
+tap.retry(3)
+  .test('should retry on failure', async (toolsArg) => {
+    // Use retry count to determine success
+    const currentRetry = toolsArg.retryCount;
+    
+    // Fail on first two attempts (0 and 1), succeed on third (2)
+    if (currentRetry < 2) {
+      throw new Error(`Attempt ${currentRetry + 1} failed`);
+    }
+    
+    expect(currentRetry).toEqual(2);
+  });
+
+tap.test('should expose retry count', async (toolsArg) => {
+  toolsArg.retry(2);
+  
+  // The retry count should be available
+  expect(toolsArg.retryCount).toBeLessThanOrEqual(2);
+  expect(true).toBeTrue();
+});
+
+// Test allowFailure
+tap.test('should allow failure', async (toolsArg) => {
+  // Just verify that allowFailure() can be called without throwing
+  toolsArg.allowFailure();
+  expect(true).toBeTrue();
+  // Note: In a real implementation, we would see "please note: failure allowed!" 
+  // in the output when this test fails, but the test itself will still be marked as failed
+});
+
+tap.start();
--- a/test/tapbundle/test.ts
+++ b/test/tapbundle/test.ts
@ -0,0 +1,49 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+tap.preTask('hi there', async () => {
+  console.log('this is a pretask');
+});
+
+const test1 = tap.test('my first test -> expect true to be true', async () => {
+  return expect(true).toBeTrue();
+});
+
+const test2 = tap.test('my second test', async (tools) => {
+  await tools.delayFor(1000);
+});
+
+const test3 = tap.test(
+  'my third test -> test2 should take longer than test1 and endure at least 1000ms',
+  async () => {
+    expect(
+      (await test1.testPromise).hrtMeasurement.milliSeconds <
+        (await test2.testPromise).hrtMeasurement.milliSeconds,
+    ).toBeTrue();
+    expect((await test2.testPromise).hrtMeasurement.milliSeconds >= 1000).toBeTrue();
+  },
+);
+
+const test4 = tap.test('my 4th test -> should fail', async (tools) => {
+  tools.allowFailure();
+  expect(false).toBeFalse();
+  return 'hello';
+});
+
+const test5 = tap.test('my 5th test -> should pass in about 500ms', async (tools) => {
+  const test4Result = await test4.testResultPromise;
+  tools.timeout(1000);
+  await tools.delayFor(500);
+});
+
+const test6 = tap.skip.test('my 6th test -> should fail after 1000ms', async (tools) => {
+  tools.allowFailure();
+  tools.timeout(1000);
+  await tools.delayFor(2000);
+});
+
+const test7 = tap.test('my 7th test -> should print a colored string', async (tools) => {
+  const cs = await tools.coloredString('hello', 'red', 'cyan');
+  console.log(cs);
+});
+
+tap.start();
--- a/test/test.ts
+++ b/test/test.ts
@ -1,6 +0,0 @@
-import { expect, tap } from '@push.rocks/tapbundle';
-import * as tstest from '../ts/index.js';
-
-tap.test('prepare test', async () => {});
-
-tap.start();
--- a/test/tstest/subdir/test.sub.ts
+++ b/test/tstest/subdir/test.sub.ts
@ -1,4 +1,4 @@
-import { expect, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '../../../ts_tapbundle/index.js';

 tap.test('subdirectory test execution', async () => {
  console.log('This test verifies subdirectory test discovery works');
--- a/test/tstest/test-parallel-demo.ts
+++ b/test/tstest/test-parallel-demo.ts
@ -0,0 +1,16 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+import * as fs from 'fs';
+
+// Test to demonstrate parallel execution timing - run with glob pattern
+// This will give us a clear view of execution order with timestamps
+
+const timestamp = () => new Date().toISOString().substr(11, 12);
+
+tap.test('demo test in main file', async (toolsArg) => {
+  console.log(`[${timestamp()}] Test parallel demo started`);
+  await toolsArg.delayFor(1000);
+  console.log(`[${timestamp()}] Test parallel demo completed`);
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.api.para__2.ts
+++ b/test/tstest/test.api.para__2.ts
@ -0,0 +1,11 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// This test runs in parallel group 2
+tap.test('api test in parallel group 2', async (toolsArg) => {
+  console.log('API test started');
+  await toolsArg.delayFor(800);
+  console.log('API test completed');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.auth.para__1.ts
+++ b/test/tstest/test.auth.para__1.ts
@ -0,0 +1,13 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// This test runs in parallel group 1
+const timestamp = () => new Date().toISOString().substr(11, 12);
+
+tap.test('auth test in parallel group 1', async (toolsArg) => {
+  console.log(`[${timestamp()}] Auth test started`);
+  await toolsArg.delayFor(1000);
+  console.log(`[${timestamp()}] Auth test completed`);
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.console.ts
+++ b/test/tstest/test.console.ts
@ -0,0 +1,11 @@
+import { expect, tap } from '../../ts_tapbundle/index.js';
+
+tap.test('Test with console output', async () => {
+  console.log('Log message 1 from test');
+  console.log('Log message 2 from test');
+  console.error('Error message from test');
+  console.warn('Warning message from test');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.db.para__2.ts
+++ b/test/tstest/test.db.para__2.ts
@ -0,0 +1,11 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// This test runs in parallel group 2
+tap.test('db test in parallel group 2', async (toolsArg) => {
+  console.log('DB test started');
+  await toolsArg.delayFor(800);
+  console.log('DB test completed');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.fail.ts
+++ b/test/tstest/test.fail.ts
@ -1,4 +1,4 @@
-import { expect, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '../../ts_tapbundle/index.js';

 tap.test('This test should fail', async () => {
  console.log('This test will fail on purpose');
--- a/test/tstest/test.failing-with-logs.ts
+++ b/test/tstest/test.failing-with-logs.ts
@ -0,0 +1,23 @@
+import { expect, tap } from '../../ts_tapbundle/index.js';
+
+tap.test('Test that will fail with console logs', async () => {
+  console.log('Starting the test...');
+  console.log('Doing some setup work');
+  console.log('About to check assertion');
+  
+  const value = 42;
+  console.log(`The value is: ${value}`);
+  
+  // This will fail
+  expect(value).toEqual(100);
+  
+  console.log('This log will not be reached');
+});
+
+tap.test('Test that passes', async () => {
+  console.log('This test passes');
+  console.log('So these logs should not show in default mode');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.glob.ts
+++ b/test/tstest/test.glob.ts
@ -1,4 +1,4 @@
-import { expect, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '../../ts_tapbundle/index.js';

 tap.test('glob pattern test execution', async () => {
  console.log('This test verifies glob pattern execution works');
--- a/test/tstest/test.serial1.ts
+++ b/test/tstest/test.serial1.ts
@ -0,0 +1,10 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// This test runs serially (no para__ in filename)
+tap.test('serial test 1', async (toolsArg) => {
+  await toolsArg.delayFor(500);
+  console.log('Serial test 1 completed');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.serial2.ts
+++ b/test/tstest/test.serial2.ts
@ -0,0 +1,10 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// This test runs serially (no para__ in filename)
+tap.test('serial test 2', async (toolsArg) => {
+  await toolsArg.delayFor(500);
+  console.log('Serial test 2 completed');
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/test/tstest/test.single.ts
+++ b/test/tstest/test.single.ts
@ -1,4 +1,4 @@
-import { expect, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '../../ts_tapbundle/index.js';

 tap.test('single file test execution', async () => {
  console.log('This test verifies single file execution works');
--- a/test/tstest/test.ts
+++ b/test/tstest/test.ts
@ -0,0 +1,6 @@
+import { expect, tap } from '../../ts_tapbundle/index.js';
+import * as tstest from '../../ts/index.js';
+
+tap.test('prepare test', async () => {});
+
+tap.start();
--- a/test/tstest/test.user.para__1.ts
+++ b/test/tstest/test.user.para__1.ts
@ -0,0 +1,13 @@
+import { tap, expect } from '../../ts_tapbundle/index.js';
+
+// This test runs in parallel group 1
+const timestamp = () => new Date().toISOString().substr(11, 12);
+
+tap.test('user test in parallel group 1', async (toolsArg) => {
+  console.log(`[${timestamp()}] User test started`);
+  await toolsArg.delayFor(1000);
+  console.log(`[${timestamp()}] User test completed`);
+  expect(true).toBeTrue();
+});
+
+tap.start();
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@git.zone/tstest',
-  version: '1.2.0',
+  version: '1.11.3',
  description: 'a test utility to run tests that match test/**/*.ts'
 }
--- a/ts/index.ts
+++ b/ts/index.ts
@ -12,6 +12,10 @@ export const runCli = async () => {
  const args = process.argv.slice(2);
  const logOptions: LogOptions = {};
  let testPath: string | null = null;
+  let tags: string[] = [];
+  let startFromFile: number | null = null;
+  let stopAtFile: number | null = null;
+  let timeoutSeconds: number | null = null;
  
  // Parse options
  for (let i = 0; i < args.length; i++) {
@ -33,8 +37,51 @@ export const runCli = async () => {
        logOptions.json = true;
        break;
      case '--log-file':
+      case '--logfile':
+        logOptions.logFile = true; // Set this as a flag, not a value
+        break;
+      case '--tags':
        if (i + 1 < args.length) {
-          logOptions.logFile = args[++i];
+          tags = args[++i].split(',');
+        }
+        break;
+      case '--startFrom':
+        if (i + 1 < args.length) {
+          const value = parseInt(args[++i], 10);
+          if (isNaN(value) || value < 1) {
+            console.error('Error: --startFrom must be a positive integer');
+            process.exit(1);
+          }
+          startFromFile = value;
+        } else {
+          console.error('Error: --startFrom requires a number argument');
+          process.exit(1);
+        }
+        break;
+      case '--stopAt':
+        if (i + 1 < args.length) {
+          const value = parseInt(args[++i], 10);
+          if (isNaN(value) || value < 1) {
+            console.error('Error: --stopAt must be a positive integer');
+            process.exit(1);
+          }
+          stopAtFile = value;
+        } else {
+          console.error('Error: --stopAt requires a number argument');
+          process.exit(1);
+        }
+        break;
+      case '--timeout':
+        if (i + 1 < args.length) {
+          const value = parseInt(args[++i], 10);
+          if (isNaN(value) || value < 1) {
+            console.error('Error: --timeout must be a positive integer (seconds)');
+            process.exit(1);
+          }
+          timeoutSeconds = value;
+        } else {
+          console.error('Error: --timeout requires a number argument (seconds)');
+          process.exit(1);
        }
        break;
      default:
@ -44,15 +91,25 @@ export const runCli = async () => {
    }
  }
  
+  // Validate test file range options
+  if (startFromFile !== null && stopAtFile !== null && startFromFile > stopAtFile) {
+    console.error('Error: --startFrom cannot be greater than --stopAt');
+    process.exit(1);
+  }
+  
  if (!testPath) {
    console.error('You must specify a test directory/file/pattern as argument. Please try again.');
    console.error('\nUsage: tstest <path> [options]');
    console.error('\nOptions:');
-    console.error('  --quiet, -q     Minimal output');
-    console.error('  --verbose, -v   Verbose output');
-    console.error('  --no-color      Disable colored output');
-    console.error('  --json          Output results as JSON');
-    console.error('  --log-file      Write logs to file');
+    console.error('  --quiet, -q       Minimal output');
+    console.error('  --verbose, -v     Verbose output');
+    console.error('  --no-color        Disable colored output');
+    console.error('  --json            Output results as JSON');
+    console.error('  --logfile         Write logs to .nogit/testlogs/[testfile].log');
+    console.error('  --tags <tags>     Run only tests with specified tags (comma-separated)');
+    console.error('  --startFrom <n>   Start running from test file number n');
+    console.error('  --stopAt <n>      Stop running at test file number n');
+    console.error('  --timeout <s>     Timeout test files after s seconds');
    process.exit(1);
  }
  
@ -67,6 +124,11 @@ export const runCli = async () => {
    executionMode = TestExecutionMode.DIRECTORY;
  }
  
-  const tsTestInstance = new TsTest(process.cwd(), testPath, executionMode, logOptions);
+  const tsTestInstance = new TsTest(process.cwd(), testPath, executionMode, logOptions, tags, startFromFile, stopAtFile, timeoutSeconds);
  await tsTestInstance.run();
 };
+
+// Execute CLI when this file is run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runCli();
+}
--- a/ts/tspublish.json
+++ b/ts/tspublish.json
@ -0,0 +1,3 @@
+{
+  "order": 2
+}
--- a/ts/tstest.classes.tap.combinator.ts
+++ b/ts/tstest.classes.tap.combinator.ts
@ -10,6 +10,7 @@ import { TsTestLogger } from './tstest.logging.js';

 export class TapCombinator {
  tapParserStore: TapParser[] = [];
+  skippedFiles: string[] = [];
  private logger: TsTestLogger;
  
  constructor(logger: TsTestLogger) {
@ -19,10 +20,14 @@ export class TapCombinator {
  addTapParser(tapParserArg: TapParser) {
    this.tapParserStore.push(tapParserArg);
  }
+  
+  addSkippedFile(filename: string) {
+    this.skippedFiles.push(filename);
+  }

  evaluate() {
-    // Call the logger's summary method
-    this.logger.summary();
+    // Call the logger's summary method with skipped files
+    this.logger.summary(this.skippedFiles);
    
    // Check for failures
    let failGlobal = false;
--- a/ts/tstest.classes.tap.parser.ts
+++ b/ts/tstest.classes.tap.parser.ts
@ -16,8 +16,10 @@ export class TapParser {
  expectedTests: number;
  receivedTests: number;

-  testStatusRegex = /(ok|not\sok)\s([0-9]+)\s-\s(.*)\s#\stime=(.*)ms$/;
+  testStatusRegex = /(ok|not\sok)\s([0-9]+)\s-\s(.*?)(\s#\s(.*))?$/;
  activeTapTestResult: TapTestResult;
+  collectingErrorDetails: boolean = false;
+  currentTestError: string[] = [];

  pretaskRegex = /^::__PRETASK:(.*)$/;
  
@ -29,6 +31,36 @@ export class TapParser {
  constructor(public fileName: string, logger?: TsTestLogger) {
    this.logger = logger;
  }
+  
+  /**
+   * Handle test file timeout
+   */
+  public handleTimeout(timeoutSeconds: number) {
+    // If no tests have been defined yet, set expected to 1
+    if (this.expectedTests === 0) {
+      this.expectedTests = 1;
+    }
+    
+    // Create a fake failing test result for timeout
+    this._getNewTapTestResult();
+    this.activeTapTestResult.testOk = false;
+    this.activeTapTestResult.testSettled = true;
+    this.testStore.push(this.activeTapTestResult);
+    
+    // Log the timeout error
+    if (this.logger) {
+      // First log the test result
+      this.logger.testResult(
+        `Test file timeout`,
+        false,
+        timeoutSeconds * 1000,
+        `Error: Test file exceeded timeout of ${timeoutSeconds} seconds`
+      );
+      this.logger.testErrorDetails(`Test execution was terminated after ${timeoutSeconds} seconds`);
+    }
+    
+    // Don't call evaluateFinalResult here, let the caller handle it
+  }

  private _getNewTapTestResult() {
    this.activeTapTestResult = new TapTestResult(this.testStore.length + 1);
@ -67,7 +99,7 @@ export class TapParser {
      } else if (this.testStatusRegex.test(logLine)) {
        logLineIsTapProtocol = true;
        const regexResult = this.testStatusRegex.exec(logLine);
-        const testId = parseInt(regexResult[2]);
+        // const testId = parseInt(regexResult[2]); // Currently unused
        const testOk = (() => {
          if (regexResult[1] === 'ok') {
            return true;
@ -75,15 +107,29 @@ export class TapParser {
          return false;
        })();

-        const testSubject = regexResult[3];
-        const testDuration = parseInt(regexResult[4]);
-
-        // test for protocol error
-        if (testId !== this.activeTapTestResult.id) {
-          if (this.logger) {
-            this.logger.error('Something is strange! Test Ids are not equal!');
+        const testSubject = regexResult[3].trim();
+        const testMetadata = regexResult[5]; // This will be either "time=XXXms" or "SKIP reason" or "TODO reason"
+        
+        let testDuration = 0;
+        
+        if (testMetadata) {
+          const timeMatch = testMetadata.match(/time=(\d+)ms/);
+          // const skipMatch = testMetadata.match(/SKIP\s*(.*)/); // Currently unused
+          // const todoMatch = testMetadata.match(/TODO\s*(.*)/); // Currently unused
+          
+          if (timeMatch) {
+            testDuration = parseInt(timeMatch[1]);
          }
+          // Skip/todo handling could be added here in the future
        }
+
+        // test for protocol error - disabled as it's not critical
+        // The test ID mismatch can occur when tests are filtered, skipped, or use todo
+        // if (testId !== this.activeTapTestResult.id) {
+        //   if (this.logger) {
+        //     this.logger.error('Something is strange! Test Ids are not equal!');
+        //   }
+        // }
        this.activeTapTestResult.setTestResult(testOk);

        if (testOk) {
@ -91,6 +137,9 @@ export class TapParser {
            this.logger.testResult(testSubject, true, testDuration);
          }
        } else {
+          // Start collecting error details for failed test
+          this.collectingErrorDetails = true;
+          this.currentTestError = [];
          if (this.logger) {
            this.logger.testResult(testSubject, false, testDuration);
          }
@ -101,12 +150,57 @@ export class TapParser {
        if (this.activeTapTestResult) {
          this.activeTapTestResult.addLogLine(logLine);
        }
-        if (this.logger) {
-          this.logger.tapOutput(logLine);
+        
+        // Check for snapshot communication
+        const snapshotMatch = logLine.match(/###SNAPSHOT###(.+)###SNAPSHOT###/);
+        if (snapshotMatch) {
+          const base64Data = snapshotMatch[1];
+          try {
+            const snapshotData = JSON.parse(Buffer.from(base64Data, 'base64').toString());
+            this.handleSnapshot(snapshotData);
+          } catch (error) {
+            if (this.logger) {
+              this.logger.testConsoleOutput(`Error parsing snapshot data: ${error.message}`);
+            }
+          }
+        } else {
+          // Check if we're collecting error details
+          if (this.collectingErrorDetails) {
+            // Check if this line is an error detail (starts with Error: or has stack trace characteristics)
+            if (logLine.trim().startsWith('Error:') || logLine.trim().match(/^\s*at\s/)) {
+              this.currentTestError.push(logLine);
+            } else if (this.currentTestError.length > 0) {
+              // End of error details, show the error
+              const errorMessage = this.currentTestError.join('\n');
+              if (this.logger) {
+                this.logger.testErrorDetails(errorMessage);
+              }
+              this.collectingErrorDetails = false;
+              this.currentTestError = [];
+            }
+          }
+          
+          // Don't output TAP error details as console output when we're collecting them
+          if (!this.collectingErrorDetails || (!logLine.trim().startsWith('Error:') && !logLine.trim().match(/^\s*at\s/))) {
+            if (this.logger) {
+              // This is console output from the test file, not TAP protocol
+              this.logger.testConsoleOutput(logLine);
+            }
+          }
        }
      }

      if (this.activeTapTestResult && this.activeTapTestResult.testSettled) {
+        // Ensure any pending error is shown before settling the test
+        if (this.collectingErrorDetails && this.currentTestError.length > 0) {
+          const errorMessage = this.currentTestError.join('\n');
+          if (this.logger) {
+            this.logger.testErrorDetails(errorMessage);
+          }
+          this.collectingErrorDetails = false;
+          this.currentTestError = [];
+        }
+        
        this.testStore.push(this.activeTapTestResult);
        this._getNewTapTestResult();
      }
@ -169,6 +263,59 @@ export class TapParser {
  public async handleTapLog(tapLog: string) {
    this._processLog(tapLog);
  }
+  
+  /**
+   * Handle snapshot data from the test
+   */
+  private async handleSnapshot(snapshotData: { path: string; content: string; action: string }) {
+    try {
+      const smartfile = await import('@push.rocks/smartfile');
+      
+      if (snapshotData.action === 'compare') {
+        // Try to read existing snapshot
+        try {
+          const existingSnapshot = await smartfile.fs.toStringSync(snapshotData.path);
+          if (existingSnapshot !== snapshotData.content) {
+            // Snapshot mismatch
+            if (this.logger) {
+              this.logger.testConsoleOutput(`Snapshot mismatch: ${snapshotData.path}`);
+              this.logger.testConsoleOutput(`Expected:\n${existingSnapshot}`);
+              this.logger.testConsoleOutput(`Received:\n${snapshotData.content}`);
+            }
+            // TODO: Communicate failure back to the test
+          } else {
+            if (this.logger) {
+              this.logger.testConsoleOutput(`Snapshot matched: ${snapshotData.path}`);
+            }
+          }
+        } catch (error: any) {
+          if (error.code === 'ENOENT') {
+            // Snapshot doesn't exist, create it
+            const dirPath = snapshotData.path.substring(0, snapshotData.path.lastIndexOf('/'));
+            await smartfile.fs.ensureDir(dirPath);
+            await smartfile.memory.toFs(snapshotData.content, snapshotData.path);
+            if (this.logger) {
+              this.logger.testConsoleOutput(`Snapshot created: ${snapshotData.path}`);
+            }
+          } else {
+            throw error;
+          }
+        }
+      } else if (snapshotData.action === 'update') {
+        // Update snapshot
+        const dirPath = snapshotData.path.substring(0, snapshotData.path.lastIndexOf('/'));
+        await smartfile.fs.ensureDir(dirPath);
+        await smartfile.memory.toFs(snapshotData.content, snapshotData.path);
+        if (this.logger) {
+          this.logger.testConsoleOutput(`Snapshot updated: ${snapshotData.path}`);
+        }
+      }
+    } catch (error: any) {
+      if (this.logger) {
+        this.logger.testConsoleOutput(`Error handling snapshot: ${error.message}`);
+      }
+    }
+  }

  public async evaluateFinalResult() {
    this.receivedTests = this.testStore.length;
@ -183,13 +330,16 @@ export class TapParser {
        this.logger.error(`Only ${this.receivedTests} out of ${this.expectedTests} completed!`);
      }
    }
-    if (!this.expectedTests) {
+    if (!this.expectedTests && this.receivedTests === 0) {
      if (this.logger) {
        this.logger.error('No tests were defined. Therefore the testfile failed!');
+        this.logger.testFileEnd(0, 1, 0); // Count as 1 failure
      }
    } else if (this.expectedTests !== this.receivedTests) {
      if (this.logger) {
        this.logger.error('The amount of received tests and expectedTests is unequal! Therefore the testfile failed');
+        const errorCount = this.getErrorTests().length || 1; // At least 1 error
+        this.logger.testFileEnd(this.receivedTests - errorCount, errorCount, 0);
      }
    } else if (this.getErrorTests().length === 0) {
      if (this.logger) {
--- a/ts/tstest.classes.testdirectory.ts
+++ b/ts/tstest.classes.testdirectory.ts
@ -99,4 +99,43 @@ export class TestDirectory {
    }
    return testFilePaths;
  }
+
+  /**
+   * Get test files organized by parallel execution groups
+   * @returns An object with grouped tests
+   */
+  async getTestFileGroups(): Promise<{
+    serial: string[];
+    parallelGroups: { [groupName: string]: string[] };
+  }> {
+    await this._init();
+    
+    const result = {
+      serial: [] as string[],
+      parallelGroups: {} as { [groupName: string]: string[] }
+    };
+    
+    for (const testFile of this.testfileArray) {
+      const filePath = testFile.path;
+      const fileName = plugins.path.basename(filePath);
+      
+      // Check if file has parallel group pattern
+      const parallelMatch = fileName.match(/\.para__(\d+)\./);
+      
+      if (parallelMatch) {
+        const groupNumber = parallelMatch[1];
+        const groupName = `para__${groupNumber}`;
+        
+        if (!result.parallelGroups[groupName]) {
+          result.parallelGroups[groupName] = [];
+        }
+        result.parallelGroups[groupName].push(filePath);
+      } else {
+        // File runs serially
+        result.serial.push(filePath);
+      }
+    }
+    
+    return result;
+  }
 }
--- a/ts/tstest.classes.tstest.ts
+++ b/ts/tstest.classes.tstest.ts
@ -1,6 +1,5 @@
 import * as plugins from './tstest.plugins.js';
 import * as paths from './tstest.paths.js';
-import * as logPrefixes from './tstest.logprefixes.js';

 import { coloredString as cs } from '@push.rocks/consolecolor';

@ -15,6 +14,11 @@ export class TsTest {
  public testDir: TestDirectory;
  public executionMode: TestExecutionMode;
  public logger: TsTestLogger;
+  public filterTags: string[];
+  public startFromFile: number | null;
+  public stopAtFile: number | null;
+  public timeoutSeconds: number | null;
+  private timeoutWarningTimer: NodeJS.Timeout | null = null;

  public smartshellInstance = new plugins.smartshell.Smartshell({
    executor: 'bash',
@ -25,53 +29,123 @@ export class TsTest {

  public tsbundleInstance = new plugins.tsbundle.TsBundle();

-  constructor(cwdArg: string, testPathArg: string, executionModeArg: TestExecutionMode, logOptions: LogOptions = {}) {
+  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;
    this.testDir = new TestDirectory(cwdArg, testPathArg, executionModeArg);
    this.logger = new TsTestLogger(logOptions);
+    this.filterTags = tags;
+    this.startFromFile = startFromFile;
+    this.stopAtFile = stopAtFile;
+    this.timeoutSeconds = timeoutSeconds;
  }

  async run() {
-    const fileNamesToRun: string[] = await this.testDir.getTestFilePathArray();
+    // Move previous log files if --logfile option is used
+    if (this.logger.options.logFile) {
+      await this.movePreviousLogFiles();
+    }
    
-    // Log test discovery
+    // Start timeout warning timer if no timeout was specified
+    if (this.timeoutSeconds === null) {
+      this.timeoutWarningTimer = setTimeout(() => {
+        // Use the logger instead of console.error to ensure the warning is visible
+        this.logger.error('Warning: Test is running for more than 1 minute.');
+        this.logger.error('Consider using --timeout option to set a timeout for test files.');
+        this.logger.error('Example: tstest test --timeout=300 (for 5 minutes)');
+      }, 60000); // 1 minute
+    }
+    
+    const testGroups = await this.testDir.getTestFileGroups();
+    const allFiles = [...testGroups.serial, ...Object.values(testGroups.parallelGroups).flat()];
+    
+    // Log test discovery - always show full count
    this.logger.testDiscovery(
-      fileNamesToRun.length, 
+      allFiles.length, 
      this.testDir.testPath,
      this.executionMode
    );

    const tapCombinator = new TapCombinator(this.logger); // lets create the TapCombinator
    let fileIndex = 0;
-    for (const fileNameArg of fileNamesToRun) {
+    
+    // Execute serial tests first
+    for (const fileNameArg of testGroups.serial) {
      fileIndex++;
-      switch (true) {
-        case process.env.CI && fileNameArg.includes('.nonci.'):
-          this.logger.tapOutput(`Skipping ${fileNameArg} - marked as non-CI`);
-          break;
-        case fileNameArg.endsWith('.browser.ts') || fileNameArg.endsWith('.browser.nonci.ts'):
-          const tapParserBrowser = await this.runInChrome(fileNameArg, fileIndex, fileNamesToRun.length);
-          tapCombinator.addTapParser(tapParserBrowser);
-          break;
-        case fileNameArg.endsWith('.both.ts') || fileNameArg.endsWith('.both.nonci.ts'):
-          this.logger.sectionStart('Part 1: Chrome');
-          const tapParserBothBrowser = await this.runInChrome(fileNameArg, fileIndex, fileNamesToRun.length);
-          tapCombinator.addTapParser(tapParserBothBrowser);
-          this.logger.sectionEnd();
-          
-          this.logger.sectionStart('Part 2: Node');
-          const tapParserBothNode = await this.runInNode(fileNameArg, fileIndex, fileNamesToRun.length);
-          tapCombinator.addTapParser(tapParserBothNode);
-          this.logger.sectionEnd();
-          break;
-        default:
-          const tapParserNode = await this.runInNode(fileNameArg, fileIndex, fileNamesToRun.length);
-          tapCombinator.addTapParser(tapParserNode);
-          break;
+      await this.runSingleTestOrSkip(fileNameArg, fileIndex, allFiles.length, tapCombinator);
+    }
+    
+    // Execute parallel groups sequentially
+    const groupNames = Object.keys(testGroups.parallelGroups).sort();
+    for (const groupName of groupNames) {
+      const groupFiles = testGroups.parallelGroups[groupName];
+      
+      if (groupFiles.length > 0) {
+        this.logger.sectionStart(`Parallel Group: ${groupName}`);
+        
+        // Run all tests in this group in parallel
+        const parallelPromises = groupFiles.map(async (fileNameArg) => {
+          fileIndex++;
+          return this.runSingleTestOrSkip(fileNameArg, fileIndex, allFiles.length, tapCombinator);
+        });
+        
+        await Promise.all(parallelPromises);
+        this.logger.sectionEnd();
      }
    }
+    
+    // Clear the timeout warning timer if it was set
+    if (this.timeoutWarningTimer) {
+      clearTimeout(this.timeoutWarningTimer);
+      this.timeoutWarningTimer = null;
+    }
+    
    tapCombinator.evaluate();
  }
+  
+  private async runSingleTestOrSkip(fileNameArg: string, fileIndex: number, totalFiles: number, tapCombinator: TapCombinator) {
+    // Check if this file should be skipped based on range
+    if (this.startFromFile !== null && fileIndex < this.startFromFile) {
+      this.logger.testFileSkipped(fileNameArg, fileIndex, totalFiles, `before start range (${this.startFromFile})`);
+      tapCombinator.addSkippedFile(fileNameArg);
+      return;
+    }
+    
+    if (this.stopAtFile !== null && fileIndex > this.stopAtFile) {
+      this.logger.testFileSkipped(fileNameArg, fileIndex, totalFiles, `after stop range (${this.stopAtFile})`);
+      tapCombinator.addSkippedFile(fileNameArg);
+      return;
+    }
+    
+    // File is in range, run it
+    await this.runSingleTest(fileNameArg, fileIndex, totalFiles, tapCombinator);
+  }
+  
+  private async runSingleTest(fileNameArg: string, fileIndex: number, totalFiles: number, tapCombinator: TapCombinator) {
+    switch (true) {
+      case process.env.CI && fileNameArg.includes('.nonci.'):
+        this.logger.tapOutput(`Skipping ${fileNameArg} - marked as non-CI`);
+        break;
+      case fileNameArg.endsWith('.browser.ts') || fileNameArg.endsWith('.browser.nonci.ts'):
+        const tapParserBrowser = await this.runInChrome(fileNameArg, fileIndex, totalFiles);
+        tapCombinator.addTapParser(tapParserBrowser);
+        break;
+      case fileNameArg.endsWith('.both.ts') || fileNameArg.endsWith('.both.nonci.ts'):
+        this.logger.sectionStart('Part 1: Chrome');
+        const tapParserBothBrowser = await this.runInChrome(fileNameArg, fileIndex, totalFiles);
+        tapCombinator.addTapParser(tapParserBothBrowser);
+        this.logger.sectionEnd();
+        
+        this.logger.sectionStart('Part 2: Node');
+        const tapParserBothNode = await this.runInNode(fileNameArg, fileIndex, totalFiles);
+        tapCombinator.addTapParser(tapParserBothNode);
+        this.logger.sectionEnd();
+        break;
+      default:
+        const tapParserNode = await this.runInNode(fileNameArg, fileIndex, totalFiles);
+        tapCombinator.addTapParser(tapParserNode);
+        break;
+    }
+  }

  public async runInNode(fileNameArg: string, index: number, total: number): Promise<TapParser> {
    this.logger.testFileStart(fileNameArg, 'node.js', index, total);
@ -82,11 +156,50 @@ export class TsTest {
    if (process.argv.includes('--web')) {
      tsrunOptions += ' --web';
    }
+    
+    // Set filter tags as environment variable
+    if (this.filterTags.length > 0) {
+      process.env.TSTEST_FILTER_TAGS = this.filterTags.join(',');
+    }

    const execResultStreaming = await this.smartshellInstance.execStreamingSilent(
      `tsrun ${fileNameArg}${tsrunOptions}`
    );
-    await tapParser.handleTapProcess(execResultStreaming.childProcess);
+    
+    // Handle timeout if specified
+    if (this.timeoutSeconds !== null) {
+      const timeoutMs = this.timeoutSeconds * 1000;
+      let timeoutId: NodeJS.Timeout;
+      
+      const timeoutPromise = new Promise<void>((_resolve, reject) => {
+        timeoutId = setTimeout(async () => {
+          // Use smartshell's terminate() to kill entire process tree
+          await execResultStreaming.terminate();
+          reject(new Error(`Test file timed out after ${this.timeoutSeconds} seconds`));
+        }, timeoutMs);
+      });
+      
+      try {
+        await Promise.race([
+          tapParser.handleTapProcess(execResultStreaming.childProcess),
+          timeoutPromise
+        ]);
+        // Clear timeout if test completed successfully
+        clearTimeout(timeoutId);
+      } catch (error) {
+        // Handle timeout error
+        tapParser.handleTimeout(this.timeoutSeconds);
+        // Ensure entire process tree is killed if still running
+        try {
+          await execResultStreaming.kill(); // This kills the entire process tree with SIGKILL
+        } catch (killError) {
+          // Process tree might already be dead
+        }
+      }
+    } else {
+      await tapParser.handleTapProcess(execResultStreaming.childProcess);
+    }
+    
    return tapParser;
  }

@ -111,7 +224,7 @@ export class TsTest {
    });
    server.addRoute(
      '/test',
-      new plugins.typedserver.servertools.Handler('GET', async (req, res) => {
+      new plugins.typedserver.servertools.Handler('GET', async (_req, res) => {
        res.type('.html');
        res.write(`
        <html>
@ -144,9 +257,10 @@ export class TsTest {
      });
    });

-    // lets do the browser bit
+    // lets do the browser bit with timeout handling
    await this.smartbrowserInstance.start();
-    const evaluation = await this.smartbrowserInstance.evaluateOnPage(
+    
+    const evaluatePromise = this.smartbrowserInstance.evaluateOnPage(
      `http://localhost:3007/test?bundleName=${bundleFileName}`,
      async () => {
        // lets enable real time comms
@ -159,12 +273,12 @@ export class TsTest {
        const originalError = console.error;

        // Override console methods to capture the logs
-        console.log = (...args) => {
+        console.log = (...args: any[]) => {
          logStore.push(args.join(' '));
          ws.send(args.join(' '));
          originalLog(...args);
        };
-        console.error = (...args) => {
+        console.error = (...args: any[]) => {
          logStore.push(args.join(' '));
          ws.send(args.join(' '));
          originalError(...args);
@ -203,16 +317,105 @@ export class TsTest {
        return logStore.join('\n');
      }
    );
-    await this.smartbrowserInstance.stop();
-    await server.stop();
-    wss.close();
+    
+    // Handle timeout if specified
+    if (this.timeoutSeconds !== null) {
+      const timeoutMs = this.timeoutSeconds * 1000;
+      let timeoutId: NodeJS.Timeout;
+      
+      const timeoutPromise = new Promise<void>((_resolve, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`Test file timed out after ${this.timeoutSeconds} seconds`));
+        }, timeoutMs);
+      });
+      
+      try {
+        await Promise.race([
+          evaluatePromise,
+          timeoutPromise
+        ]);
+        // Clear timeout if test completed successfully
+        clearTimeout(timeoutId);
+      } catch (error) {
+        // Handle timeout error
+        tapParser.handleTimeout(this.timeoutSeconds);
+      }
+    } else {
+      await evaluatePromise;
+    }
+    
+    // Always clean up resources, even on timeout
+    try {
+      await this.smartbrowserInstance.stop();
+    } catch (error) {
+      // Browser might already be stopped
+    }
+    
+    try {
+      await server.stop();
+    } catch (error) {
+      // Server might already be stopped
+    }
+    
+    try {
+      wss.close();
+    } catch (error) {
+      // WebSocket server might already be closed
+    }
+    
    console.log(
      `${cs('=> ', 'blue')} Stopped ${cs(fileNameArg, 'orange')} chromium instance and server.`
    );
-    // lets create the tap parser
+    // Always evaluate final result (handleTimeout just sets up the test state)
    await tapParser.evaluateFinalResult();
    return tapParser;
  }

  public async runInDeno() {}
+  
+  private async movePreviousLogFiles() {
+    const logDir = plugins.path.join('.nogit', 'testlogs');
+    const previousDir = plugins.path.join('.nogit', 'testlogs', 'previous');
+    const errDir = plugins.path.join('.nogit', 'testlogs', '00err');
+    const diffDir = plugins.path.join('.nogit', 'testlogs', '00diff');
+    
+    try {
+      // Delete 00err and 00diff directories if they exist
+      if (await plugins.smartfile.fs.isDirectory(errDir)) {
+        await plugins.smartfile.fs.remove(errDir);
+      }
+      if (await plugins.smartfile.fs.isDirectory(diffDir)) {
+        await plugins.smartfile.fs.remove(diffDir);
+      }
+      
+      // Get all .log files in log directory (not in subdirectories)
+      const files = await plugins.smartfile.fs.listFileTree(logDir, '*.log');
+      const logFiles = files.filter((file: string) => !file.includes('/'));
+      
+      if (logFiles.length === 0) {
+        return;
+      }
+      
+      // Ensure previous directory exists
+      await plugins.smartfile.fs.ensureDir(previousDir);
+      
+      // Move each log file to previous directory
+      for (const file of logFiles) {
+        const filename = plugins.path.basename(file);
+        const sourcePath = plugins.path.join(logDir, filename);
+        const destPath = plugins.path.join(previousDir, filename);
+        
+        try {
+          // Copy file to new location and remove original
+          await plugins.smartfile.fs.copy(sourcePath, destPath);
+          await plugins.smartfile.fs.remove(sourcePath);
+        } catch (error) {
+          // Silently continue if a file can't be moved
+        }
+      }
+    } catch (error) {
+      // Directory might not exist, which is fine
+      return;
+    }
+  }
 }
--- a/ts/tstest.logging.ts
+++ b/ts/tstest.logging.ts
@ -1,12 +1,14 @@
 import { coloredString as cs } from '@push.rocks/consolecolor';
 import * as plugins from './tstest.plugins.js';
+import * as fs from 'fs';
+import * as path from 'path';

 export interface LogOptions {
  quiet?: boolean;
  verbose?: boolean;
  noColor?: boolean;
  json?: boolean;
-  logFile?: string;
+  logFile?: boolean;
 }

 export interface TestFileResult {
@ -28,15 +30,20 @@ export interface TestSummary {
  totalTests: number;
  totalPassed: number;
  totalFailed: number;
+  totalSkipped: number;
  totalDuration: number;
  fileResults: TestFileResult[];
+  skippedFiles: string[];
 }

 export class TsTestLogger {
-  private options: LogOptions;
+  public readonly options: LogOptions;
  private startTime: number;
  private fileResults: TestFileResult[] = [];
  private currentFileResult: TestFileResult | null = null;
+  private currentTestLogFile: string | null = null;
+  private currentTestLogs: string[] = []; // Buffer for current test logs
+  private currentTestFailed: boolean = false;
  
  constructor(options: LogOptions = {}) {
    this.options = options;
@ -51,11 +58,44 @@ export class TsTestLogger {
  }
  
  private log(message: string) {
-    if (this.options.json) return;
+    if (this.options.json) {
+      // For JSON mode, skip console output
+      // JSON output is handled by logJson method
+      return;
+    }
+    
    console.log(message);
    
-    if (this.options.logFile) {
-      // TODO: Implement file logging
+    // Log to the current test file log if we're in a test and --logfile is specified
+    if (this.currentTestLogFile) {
+      this.logToTestFile(message);
+    }
+  }
+  
+  private logToFile(message: string) {
+    // This method is no longer used since we use logToTestFile for individual test logs
+    // Keeping it for potential future use with a global log file
+  }
+  
+  private logToTestFile(message: string) {
+    try {
+      // Remove ANSI color codes for file logging
+      const cleanMessage = message.replace(/\u001b\[[0-9;]*m/g, '');
+      
+      // Append to test log file
+      fs.appendFileSync(this.currentTestLogFile, cleanMessage + '\n');
+    } catch (error) {
+      // Silently fail to avoid disrupting the test run
+    }
+  }
+  
+  private logJson(data: any) {
+    const jsonString = JSON.stringify(data);
+    console.log(jsonString);
+    
+    // Also log to test file if --logfile is specified
+    if (this.currentTestLogFile) {
+      this.logToTestFile(jsonString);
    }
  }
  
@ -84,7 +124,7 @@ export class TsTestLogger {
  // Test discovery
  testDiscovery(count: number, pattern: string, executionMode: string) {
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'discovery', count, pattern, executionMode }));
+      this.logJson({ event: 'discovery', count, pattern, executionMode });
      return;
    }
    
@ -109,8 +149,35 @@ export class TsTestLogger {
      tests: []
    };
    
+    // Reset test-specific state
+    this.currentTestLogs = [];
+    this.currentTestFailed = false;
+    
+    // Only set up test log file if --logfile option is specified
+    if (this.options.logFile) {
+      // 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);
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+      
+      // Clear the log file for this test
+      fs.writeFileSync(this.currentTestLogFile, '');
+    }
+    
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'fileStart', filename, runtime, index, total }));
+      this.logJson({ event: 'fileStart', filename, runtime, index, total });
      return;
    }
    
@ -128,15 +195,24 @@ export class TsTestLogger {
        this.currentFileResult.passed++;
      } else {
        this.currentFileResult.failed++;
+        this.currentTestFailed = true;
      }
      this.currentFileResult.duration += duration;
    }
    
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'testResult', testName, passed, duration, error }));
+      this.logJson({ event: 'testResult', testName, passed, duration, error });
      return;
    }
    
+    // If test failed and we have buffered logs, show them now
+    if (!passed && this.currentTestLogs.length > 0 && !this.options.verbose) {
+      this.log(this.format('   📋 Console output from failed test:', 'yellow'));
+      this.currentTestLogs.forEach(logMessage => {
+        this.log(this.format(`   ${logMessage}`, 'dim'));
+      });
+    }
+    
    const icon = passed ? '✅' : '❌';
    const color = passed ? 'green' : 'red';
    
@ -148,6 +224,9 @@ export class TsTestLogger {
        this.log(this.format(`      ${error}`, 'red'));
      }
    }
+    
+    // Clear logs after each test
+    this.currentTestLogs = [];
  }
  
  testFileEnd(passed: number, failed: number, duration: number) {
@ -157,7 +236,7 @@ export class TsTestLogger {
    }
    
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'fileEnd', passed, failed, duration }));
+      this.logJson({ event: 'fileEnd', passed, failed, duration });
      return;
    }
    
@ -167,23 +246,99 @@ export class TsTestLogger {
      const color = failed === 0 ? 'green' : 'red';
      this.log(this.format(`   Summary: ${passed}/${total} ${status}`, color));
    }
+    
+    // If using --logfile, handle error copy and diff detection
+    if (this.options.logFile && this.currentTestLogFile) {
+      try {
+        const logContent = fs.readFileSync(this.currentTestLogFile, 'utf-8');
+        const logDir = path.dirname(this.currentTestLogFile);
+        const logBasename = path.basename(this.currentTestLogFile);
+        
+        // Create error copy if there were failures
+        if (failed > 0) {
+          const errorDir = path.join(logDir, '00err');
+          if (!fs.existsSync(errorDir)) {
+            fs.mkdirSync(errorDir, { recursive: true });
+          }
+          const errorLogPath = path.join(errorDir, logBasename);
+          fs.writeFileSync(errorLogPath, logContent);
+        }
+        
+        // Check for previous version and create diff if changed
+        const previousLogPath = path.join(logDir, 'previous', logBasename);
+        if (fs.existsSync(previousLogPath)) {
+          const previousContent = fs.readFileSync(previousLogPath, 'utf-8');
+          
+          // Simple check if content differs
+          if (previousContent !== logContent) {
+            const diffDir = path.join(logDir, '00diff');
+            if (!fs.existsSync(diffDir)) {
+              fs.mkdirSync(diffDir, { recursive: true });
+            }
+            const diffLogPath = path.join(diffDir, logBasename);
+            const diffContent = this.createDiff(previousContent, logContent, logBasename);
+            fs.writeFileSync(diffLogPath, diffContent);
+          }
+        }
+      } catch (error) {
+        // Silently fail to avoid disrupting the test run
+      }
+    }
+    
+    // Clear the current test log file reference only if using --logfile
+    if (this.options.logFile) {
+      this.currentTestLogFile = null;
+    }
  }
  
-  // TAP output forwarding
-  tapOutput(message: string, isError: boolean = false) {
+  // TAP output forwarding (for TAP protocol messages)
+  tapOutput(message: string, _isError: boolean = false) {
    if (this.options.json) return;
    
-    if (this.options.verbose || isError) {
-      const prefix = isError ? '   ⚠️ ' : '   ';
-      const color = isError ? 'red' : 'dim';
-      this.log(this.format(`${prefix}${message}`, color));
+    // Never show raw TAP protocol messages in console
+    // They are already processed by TapParser and shown in our format
+    
+    // Always log to test file if --logfile is specified
+    if (this.currentTestLogFile) {
+      this.logToTestFile(`   ${message}`);
    }
  }
  
+  // Console output from test files (non-TAP output)
+  testConsoleOutput(message: string) {
+    if (this.options.json) return;
+    
+    // In verbose mode, show console output immediately
+    if (this.options.verbose) {
+      this.log(this.format(`   ${message}`, 'dim'));
+    } else {
+      // In non-verbose mode, buffer the logs
+      this.currentTestLogs.push(message);
+    }
+    
+    // Always log to test file if --logfile is specified
+    if (this.currentTestLogFile) {
+      this.logToTestFile(`   ${message}`);
+    }
+  }
+  
+  // Skipped test file
+  testFileSkipped(filename: string, index: number, total: number, reason: string) {
+    if (this.options.json) {
+      this.logJson({ event: 'fileSkipped', filename, index, total, reason });
+      return;
+    }
+    
+    if (this.options.quiet) return;
+    
+    this.log(this.format(`\n⏭️  ${filename} (${index}/${total})`, 'yellow'));
+    this.log(this.format(`   Skipped: ${reason}`, 'dim'));
+  }
+  
  // Browser console
  browserConsole(message: string, level: string = 'log') {
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'browserConsole', message, level }));
+      this.logJson({ event: 'browserConsole', message, level });
      return;
    }
    
@ -194,20 +349,42 @@ export class TsTestLogger {
    }
  }
  
+  // Test error details display
+  testErrorDetails(errorMessage: string) {
+    if (this.options.json) {
+      this.logJson({ event: 'testError', error: errorMessage });
+      return;
+    }
+    
+    if (!this.options.quiet) {
+      this.log(this.format('      Error details:', 'red'));
+      errorMessage.split('\n').forEach(line => {
+        this.log(this.format(`        ${line}`, 'red'));
+      });
+    }
+    
+    // Always log to test file if --logfile is specified
+    if (this.currentTestLogFile) {
+      this.logToTestFile(`   Error: ${errorMessage}`);
+    }
+  }
+  
  // Final summary
-  summary() {
+  summary(skippedFiles: string[] = []) {
    const totalDuration = Date.now() - this.startTime;
    const summary: TestSummary = {
-      totalFiles: this.fileResults.length,
+      totalFiles: this.fileResults.length + skippedFiles.length,
      totalTests: this.fileResults.reduce((sum, r) => sum + r.total, 0),
      totalPassed: this.fileResults.reduce((sum, r) => sum + r.passed, 0),
      totalFailed: this.fileResults.reduce((sum, r) => sum + r.failed, 0),
+      totalSkipped: skippedFiles.length,
      totalDuration,
-      fileResults: this.fileResults
+      fileResults: this.fileResults,
+      skippedFiles
    };
    
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'summary', summary }));
+      this.logJson({ event: 'summary', summary });
      return;
    }
    
@ -224,6 +401,9 @@ export class TsTestLogger {
    this.log(this.format(`│ Total Tests:    ${summary.totalTests.toString().padStart(14)} │`, 'white'));
    this.log(this.format(`│ Passed:         ${summary.totalPassed.toString().padStart(14)} │`, 'green'));
    this.log(this.format(`│ Failed:         ${summary.totalFailed.toString().padStart(14)} │`, summary.totalFailed > 0 ? 'red' : 'green'));
+    if (summary.totalSkipped > 0) {
+      this.log(this.format(`│ Skipped:        ${summary.totalSkipped.toString().padStart(14)} │`, 'yellow'));
+    }
    this.log(this.format(`│ Duration:       ${totalDuration.toString().padStart(14)}ms │`, 'white'));
    this.log(this.format('└────────────────────────────────┘', 'dim'));
    
@ -266,7 +446,7 @@ export class TsTestLogger {
  // Error display
  error(message: string, file?: string, stack?: string) {
    if (this.options.json) {
-      console.log(JSON.stringify({ event: 'error', message, file, stack }));
+      this.logJson({ event: 'error', message, file, stack });
      return;
    }
    
@ -282,4 +462,48 @@ export class TsTestLogger {
      }
    }
  }
+  
+  // Create a diff between two log contents
+  private createDiff(previousContent: string, currentContent: string, filename: string): string {
+    const previousLines = previousContent.split('\n');
+    const currentLines = currentContent.split('\n');
+    
+    let diff = `DIFF REPORT: ${filename}\n`;
+    diff += `Generated: ${new Date().toISOString()}\n`;
+    diff += '='.repeat(80) + '\n\n';
+    
+    // Simple line-by-line comparison
+    const maxLines = Math.max(previousLines.length, currentLines.length);
+    let hasChanges = false;
+    
+    for (let i = 0; i < maxLines; i++) {
+      const prevLine = previousLines[i] || '';
+      const currLine = currentLines[i] || '';
+      
+      if (prevLine !== currLine) {
+        hasChanges = true;
+        if (i < previousLines.length && i >= currentLines.length) {
+          // Line was removed
+          diff += `- [Line ${i + 1}] ${prevLine}\n`;
+        } else if (i >= previousLines.length && i < currentLines.length) {
+          // Line was added
+          diff += `+ [Line ${i + 1}] ${currLine}\n`;
+        } else {
+          // Line was modified
+          diff += `- [Line ${i + 1}] ${prevLine}\n`;
+          diff += `+ [Line ${i + 1}] ${currLine}\n`;
+        }
+      }
+    }
+    
+    if (!hasChanges) {
+      diff += 'No changes detected.\n';
+    }
+    
+    diff += '\n' + '='.repeat(80) + '\n';
+    diff += `Previous version had ${previousLines.length} lines\n`;
+    diff += `Current version has ${currentLines.length} lines\n`;
+    
+    return diff;
+  }
 }
--- a/ts/tstest.plugins.ts
+++ b/ts/tstest.plugins.ts
@ -18,7 +18,7 @@ import * as smartfile from '@push.rocks/smartfile';
 import * as smartlog from '@push.rocks/smartlog';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartshell from '@push.rocks/smartshell';
-import * as tapbundle from '@push.rocks/tapbundle';
+import * as tapbundle from '../dist_ts_tapbundle/index.js';

 export {
  consolecolor,
--- a/ts_tapbundle/00_commitinfo_data.ts
+++ b/ts_tapbundle/00_commitinfo_data.ts
@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/tapbundle',
+  version: '6.0.3',
+  description: 'A comprehensive testing automation library that provides a wide range of utilities and tools for TAP (Test Anything Protocol) based testing, especially suitable for projects using tapbuffer.'
+}
--- a/ts_tapbundle/index.ts
+++ b/ts_tapbundle/index.ts
@ -0,0 +1,11 @@
+export { tap } from './tapbundle.classes.tap.js';
+export { TapWrap } from './tapbundle.classes.tapwrap.js';
+export { webhelpers } from './webhelpers.js';
+
+// Protocol utilities (for future protocol v2)
+export * from './tapbundle.protocols.js';
+export { TapTools } from './tapbundle.classes.taptools.js';
+
+import { expect } from '@push.rocks/smartexpect';
+
+export { expect };
--- a/ts_tapbundle/tapbundle.classes.pretask.ts
+++ b/ts_tapbundle/tapbundle.classes.pretask.ts
@ -0,0 +1,21 @@
+import * as plugins from './tapbundle.plugins.js';
+import { TapTools } from './tapbundle.classes.taptools.js';
+
+export interface IPreTaskFunction {
+  (tapTools?: TapTools): Promise<any>;
+}
+
+export class PreTask {
+  public description: string;
+  public preTaskFunction: IPreTaskFunction;
+
+  constructor(descriptionArg: string, preTaskFunctionArg: IPreTaskFunction) {
+    this.description = descriptionArg;
+    this.preTaskFunction = preTaskFunctionArg;
+  }
+
+  public async run() {
+    console.log(`::__PRETASK: ${this.description}`);
+    await this.preTaskFunction(new TapTools(null));
+  }
+}
--- a/ts_tapbundle/tapbundle.classes.tap.ts
+++ b/ts_tapbundle/tapbundle.classes.tap.ts
@ -0,0 +1,497 @@
+import * as plugins from './tapbundle.plugins.js';
+
+import { type IPreTaskFunction, PreTask } from './tapbundle.classes.pretask.js';
+import { TapTest, type ITestFunction } from './tapbundle.classes.taptest.js';
+
+export interface ITestSuite {
+  description: string;
+  tests: TapTest<any>[];
+  beforeEach?: ITestFunction<any>;
+  afterEach?: ITestFunction<any>;
+  parent?: ITestSuite;
+  children: ITestSuite[];
+}
+
+class TestBuilder<T> {
+  private _tap: Tap<T>;
+  private _tags: string[] = [];
+  private _priority: 'high' | 'medium' | 'low' = 'medium';
+  private _retryCount?: number;
+  private _timeoutMs?: number;
+  
+  constructor(tap: Tap<T>) {
+    this._tap = tap;
+  }
+  
+  tags(...tags: string[]) {
+    this._tags = tags;
+    return this;
+  }
+  
+  priority(level: 'high' | 'medium' | 'low') {
+    this._priority = level;
+    return this;
+  }
+  
+  retry(count: number) {
+    this._retryCount = count;
+    return this;
+  }
+  
+  timeout(ms: number) {
+    this._timeoutMs = ms;
+    return this;
+  }
+  
+  test(description: string, testFunction: ITestFunction<T>) {
+    const test = this._tap.test(description, testFunction, 'normal');
+    
+    // Apply settings to the test
+    if (this._tags.length > 0) {
+      test.tags = this._tags;
+    }
+    test.priority = this._priority;
+    
+    if (this._retryCount !== undefined) {
+      test.tapTools.retry(this._retryCount);
+    }
+    if (this._timeoutMs !== undefined) {
+      test.timeoutMs = this._timeoutMs;
+    }
+    
+    return test;
+  }
+  
+  testOnly(description: string, testFunction: ITestFunction<T>) {
+    const test = this._tap.test(description, testFunction, 'only');
+    
+    // Apply settings to the test
+    if (this._tags.length > 0) {
+      test.tags = this._tags;
+    }
+    test.priority = this._priority;
+    
+    if (this._retryCount !== undefined) {
+      test.tapTools.retry(this._retryCount);
+    }
+    if (this._timeoutMs !== undefined) {
+      test.timeoutMs = this._timeoutMs;
+    }
+    
+    return test;
+  }
+  
+  testSkip(description: string, testFunction: ITestFunction<T>) {
+    const test = this._tap.test(description, testFunction, 'skip');
+    
+    // Apply settings to the test
+    if (this._tags.length > 0) {
+      test.tags = this._tags;
+    }
+    test.priority = this._priority;
+    
+    if (this._retryCount !== undefined) {
+      test.tapTools.retry(this._retryCount);
+    }
+    if (this._timeoutMs !== undefined) {
+      test.timeoutMs = this._timeoutMs;
+    }
+    
+    return test;
+  }
+}
+
+export class Tap<T> {
+  private _skipCount = 0;
+  private _filterTags: string[] = [];
+  
+  constructor() {
+    // Get filter tags from environment
+    if (typeof process !== 'undefined' && process.env && process.env.TSTEST_FILTER_TAGS) {
+      this._filterTags = process.env.TSTEST_FILTER_TAGS.split(',');
+    }
+  }
+  
+  // Fluent test builder
+  public tags(...tags: string[]) {
+    const builder = new TestBuilder<T>(this);
+    return builder.tags(...tags);
+  }
+  
+  public priority(level: 'high' | 'medium' | 'low') {
+    const builder = new TestBuilder<T>(this);
+    return builder.priority(level);
+  }
+  
+  public retry(count: number) {
+    const builder = new TestBuilder<T>(this);
+    return builder.retry(count);
+  }
+  
+  public timeout(ms: number) {
+    const builder = new TestBuilder<T>(this);
+    return builder.timeout(ms);
+  }
+  
+  /**
+   * skips a test
+   * tests marked with tap.skip.test() are never executed
+   */
+  public skip = {
+    test: (descriptionArg: string, functionArg: ITestFunction<T>) => {
+      console.log(`skipped test: ${descriptionArg}`);
+      this._skipCount++;
+    },
+    testParallel: (descriptionArg: string, functionArg: ITestFunction<T>) => {
+      console.log(`skipped test: ${descriptionArg}`);
+      this._skipCount++;
+    },
+  };
+
+  /**
+   * only executes tests marked as ONLY
+   */
+  public only = {
+    test: (descriptionArg: string, testFunctionArg: ITestFunction<T>) => {
+      this.test(descriptionArg, testFunctionArg, 'only');
+    },
+  };
+
+  private _tapPreTasks: PreTask[] = [];
+  private _tapTests: TapTest<any>[] = [];
+  private _tapTestsOnly: TapTest<any>[] = [];
+  private _currentSuite: ITestSuite | null = null;
+  private _rootSuites: ITestSuite[] = [];
+
+  /**
+   * Normal test function, will run one by one
+   * @param testDescription - A description of what the test does
+   * @param testFunction - A Function that returns a Promise and resolves or rejects
+   */
+  public test(
+    testDescription: string,
+    testFunction: ITestFunction<T>,
+    modeArg: 'normal' | 'only' | 'skip' = 'normal'
+  ): TapTest<T> {
+    const localTest = new TapTest<T>({
+      description: testDescription,
+      testFunction,
+      parallel: false,
+    });
+    
+    // No options applied here - use the fluent builder syntax instead
+    
+    // If we're in a suite, add test to the suite
+    if (this._currentSuite) {
+      this._currentSuite.tests.push(localTest);
+    } else {
+      // Otherwise add to global test list
+      if (modeArg === 'normal') {
+        this._tapTests.push(localTest);
+      } else if (modeArg === 'only') {
+        this._tapTestsOnly.push(localTest);
+      }
+    }
+    return localTest;
+  }
+
+  public preTask(descriptionArg: string, functionArg: IPreTaskFunction) {
+    this._tapPreTasks.push(new PreTask(descriptionArg, functionArg));
+  }
+
+  /**
+   * A parallel test that will not be waited for before the next starts.
+   * @param testDescription - A description of what the test does
+   * @param testFunction - A Function that returns a Promise and resolves or rejects
+   */
+  public testParallel(testDescription: string, testFunction: ITestFunction<T>) {
+    const localTest = new TapTest({
+      description: testDescription,
+      testFunction,
+      parallel: true,
+    });
+    
+    if (this._currentSuite) {
+      this._currentSuite.tests.push(localTest);
+    } else {
+      this._tapTests.push(localTest);
+    }
+  }
+  
+  /**
+   * Create a test suite for grouping related tests
+   */
+  public describe(description: string, suiteFunction: () => void) {
+    const suite: ITestSuite = {
+      description,
+      tests: [],
+      children: [],
+      parent: this._currentSuite,
+    };
+    
+    // Add to parent or root
+    if (this._currentSuite) {
+      this._currentSuite.children.push(suite);
+    } else {
+      this._rootSuites.push(suite);
+    }
+    
+    // Execute suite function in context
+    const previousSuite = this._currentSuite;
+    this._currentSuite = suite;
+    try {
+      suiteFunction();
+    } finally {
+      this._currentSuite = previousSuite;
+    }
+  }
+  
+  /**
+   * Set up a function to run before each test in the current suite
+   */
+  public beforeEach(setupFunction: ITestFunction<any>) {
+    if (this._currentSuite) {
+      this._currentSuite.beforeEach = setupFunction;
+    } else {
+      throw new Error('beforeEach can only be used inside a describe block');
+    }
+  }
+  
+  /**
+   * Set up a function to run after each test in the current suite
+   */
+  public afterEach(teardownFunction: ITestFunction<any>) {
+    if (this._currentSuite) {
+      this._currentSuite.afterEach = teardownFunction;
+    } else {
+      throw new Error('afterEach can only be used inside a describe block');
+    }
+  }
+
+  /**
+   * collect all tests from suites
+   */
+  private _collectTests(suite: ITestSuite, tests: TapTest<any>[] = []): TapTest<any>[] {
+    tests.push(...suite.tests);
+    for (const childSuite of suite.children) {
+      this._collectTests(childSuite, tests);
+    }
+    return tests;
+  }
+  
+  /**
+   * starts the test evaluation
+   */
+  public async start(optionsArg?: { throwOnError: boolean }) {
+    // lets set the tapbundle promise
+    const smartenvInstance = new plugins.smartenv.Smartenv();
+    const globalPromise = plugins.smartpromise.defer();
+    smartenvInstance.isBrowser
+      ? ((globalThis as any).tapbundleDeferred = globalPromise)
+      : null;
+    // Also set tapPromise for backwards compatibility
+    smartenvInstance.isBrowser
+      ? ((globalThis as any).tapPromise = globalPromise.promise)
+      : null;
+    
+    // Path helpers will be initialized by the Node.js environment if available
+
+    // lets continue with running the tests
+    const promiseArray: Array<Promise<any>> = [];
+    
+    // Collect all tests including those in suites
+    let allTests: TapTest<any>[] = [...this._tapTests];
+    for (const suite of this._rootSuites) {
+      this._collectTests(suite, allTests);
+    }
+
+    // safeguard against empty test array
+    if (allTests.length === 0 && this._tapTestsOnly.length === 0) {
+      console.log('no tests specified. Ending here!');
+      return;
+    }
+
+    // determine which tests to run
+    let concerningTests: TapTest[];
+    if (this._tapTestsOnly.length > 0) {
+      concerningTests = this._tapTestsOnly;
+    } else {
+      concerningTests = allTests;
+    }
+    
+    // Filter tests by tags if specified
+    if (this._filterTags.length > 0) {
+      concerningTests = concerningTests.filter(test => {
+        // Skip tests without tags when filtering is active
+        if (!test.tags || test.tags.length === 0) {
+          return false;
+        }
+        // Check if test has any of the filter tags
+        return test.tags.some(tag => this._filterTags.includes(tag));
+      });
+    }
+
+    // lets run the pretasks
+    for (const preTask of this._tapPreTasks) {
+      await preTask.run();
+    }
+
+    // Count actual tests that will be run
+    console.log(`1..${concerningTests.length}`);
+    
+    // Run tests from suites with lifecycle hooks
+    let testKey = 0;
+    
+    // Run root suite tests with lifecycle hooks
+    if (this._rootSuites.length > 0) {
+      await this._runSuite(null, this._rootSuites, promiseArray, { testKey });
+      // Update testKey after running suite tests
+      for (const suite of this._rootSuites) {
+        const suiteTests = this._collectTests(suite);
+        testKey += suiteTests.length;
+      }
+    }
+    
+    // Run non-suite tests (tests added directly without describe)
+    const nonSuiteTests = concerningTests.filter(test => {
+      // Check if test is not in any suite
+      for (const suite of this._rootSuites) {
+        const suiteTests = this._collectTests(suite);
+        if (suiteTests.includes(test)) {
+          return false;
+        }
+      }
+      return true;
+    });
+    
+    for (const currentTest of nonSuiteTests) {
+      const testPromise = currentTest.run(testKey++);
+      if (currentTest.parallel) {
+        promiseArray.push(testPromise);
+      } else {
+        await testPromise;
+      }
+    }
+    
+    await Promise.all(promiseArray);
+
+    // when tests have been run and all promises are fullfilled
+    const failReasons: string[] = [];
+    const executionNotes: string[] = [];
+    // collect failed tests
+    for (const tapTest of concerningTests) {
+      if (tapTest.status !== 'success' && tapTest.status !== 'skipped') {
+        failReasons.push(
+          `Test ${tapTest.testKey + 1} failed with status ${tapTest.status}:\n` +
+            `|| ${tapTest.description}\n` +
+            `|| for more information please take a look the logs above`,
+        );
+      }
+    }
+
+    // render fail Reasons
+    for (const failReason of failReasons) {
+      console.log(failReason);
+    }
+
+    if (optionsArg && optionsArg.throwOnError && failReasons.length > 0) {
+      if (!smartenvInstance.isBrowser && typeof process !== 'undefined') process.exit(1);
+    }
+    if (smartenvInstance.isBrowser) {
+      globalPromise.resolve();
+    }
+  }
+  
+  /**
+   * Run tests in a suite with lifecycle hooks
+   */
+  private async _runSuite(
+    parentSuite: ITestSuite | null,
+    suites: ITestSuite[],
+    promiseArray: Promise<any>[],
+    context: { testKey: number }
+  ) {
+    for (const suite of suites) {
+      // Run beforeEach from parent suites
+      const beforeEachFunctions: ITestFunction<any>[] = [];
+      let currentSuite: ITestSuite | null = suite;
+      while (currentSuite) {
+        if (currentSuite.beforeEach) {
+          beforeEachFunctions.unshift(currentSuite.beforeEach);
+        }
+        currentSuite = currentSuite.parent || null;
+      }
+      
+      // Run tests in this suite
+      for (const test of suite.tests) {
+        // Create wrapper test function that includes lifecycle hooks
+        const originalFunction = test.testFunction;
+        test.testFunction = async (tapTools) => {
+          // Run all beforeEach hooks
+          for (const beforeEach of beforeEachFunctions) {
+            await beforeEach(tapTools);
+          }
+          
+          // Run the actual test
+          const result = await originalFunction(tapTools);
+          
+          // Run afterEach hooks in reverse order
+          const afterEachFunctions: ITestFunction<any>[] = [];
+          currentSuite = suite;
+          while (currentSuite) {
+            if (currentSuite.afterEach) {
+              afterEachFunctions.push(currentSuite.afterEach);
+            }
+            currentSuite = currentSuite.parent || null;
+          }
+          
+          for (const afterEach of afterEachFunctions) {
+            await afterEach(tapTools);
+          }
+          
+          return result;
+        };
+        
+        const testPromise = test.run(context.testKey++);
+        if (test.parallel) {
+          promiseArray.push(testPromise);
+        } else {
+          await testPromise;
+        }
+      }
+      
+      // Recursively run child suites
+      await this._runSuite(suite, suite.children, promiseArray, context);
+    }
+  }
+
+  public async stopForcefully(codeArg = 0, directArg = false) {
+    console.log(`tap stopping forcefully! Code: ${codeArg} / Direct: ${directArg}`);
+    if (typeof process !== 'undefined') {
+      if (directArg) {
+        process.exit(codeArg);
+      } else {
+        setTimeout(() => {
+          process.exit(codeArg);
+        }, 10);
+      }
+    }
+  }
+
+  /**
+   * handle errors
+   */
+  public threw(err: Error) {
+    console.log(err);
+  }
+
+  /**
+   * Explicitly fail the current test with a custom message
+   * @param message - The failure message to display
+   */
+  public fail(message: string = 'Test failed'): never {
+    throw new Error(message);
+  }
+}
+
+export const tap = new Tap();
--- a/ts_tapbundle/tapbundle.classes.taptest.ts
+++ b/ts_tapbundle/tapbundle.classes.taptest.ts
@ -0,0 +1,153 @@
+import * as plugins from './tapbundle.plugins.js';
+import { tapCreator } from './tapbundle.tapcreator.js';
+import { TapTools, SkipError } from './tapbundle.classes.taptools.js';
+
+// imported interfaces
+import { Deferred } from '@push.rocks/smartpromise';
+import { HrtMeasurement } from '@push.rocks/smarttime';
+
+// interfaces
+export type TTestStatus = 'success' | 'error' | 'pending' | 'errorAfterSuccess' | 'timeout' | 'skipped';
+
+export interface ITestFunction<T> {
+  (tapTools?: TapTools): Promise<T>;
+}
+
+export class TapTest<T = unknown> {
+  public description: string;
+  public failureAllowed: boolean;
+  public hrtMeasurement: HrtMeasurement;
+  public parallel: boolean;
+  public status: TTestStatus;
+  public tapTools: TapTools;
+  public testFunction: ITestFunction<T>;
+  public testKey: number; // the testKey the position in the test qeue. Set upon calling .run()
+  public timeoutMs?: number;
+  public isTodo: boolean = false;
+  public todoReason?: string;
+  public tags: string[] = [];
+  public priority: 'high' | 'medium' | 'low' = 'medium';
+  public fileName?: string;
+  private testDeferred: Deferred<TapTest<T>> = plugins.smartpromise.defer();
+  public testPromise: Promise<TapTest<T>> = this.testDeferred.promise;
+  private testResultDeferred: Deferred<T> = plugins.smartpromise.defer();
+  public testResultPromise: Promise<T> = this.testResultDeferred.promise;
+  /**
+   * constructor
+   */
+  constructor(optionsArg: {
+    description: string;
+    testFunction: ITestFunction<T>;
+    parallel: boolean;
+  }) {
+    this.description = optionsArg.description;
+    this.hrtMeasurement = new HrtMeasurement();
+    this.parallel = optionsArg.parallel;
+    this.status = 'pending';
+    this.tapTools = new TapTools(this);
+    this.testFunction = optionsArg.testFunction;
+  }
+
+  /**
+   * run the test
+   */
+  public async run(testKeyArg: number) {
+    this.testKey = testKeyArg;
+    const testNumber = testKeyArg + 1;
+    
+    // Handle todo tests
+    if (this.isTodo) {
+      const todoText = this.todoReason ? `# TODO ${this.todoReason}` : '# TODO';
+      console.log(`ok ${testNumber} - ${this.description} ${todoText}`);
+      this.status = 'success';
+      this.testDeferred.resolve(this);
+      return;
+    }
+    
+    // Run test with retries
+    let lastError: any;
+    const maxRetries = this.tapTools.maxRetries;
+    
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      this.hrtMeasurement.start();
+      
+      try {
+        // Set up timeout if specified
+        let timeoutHandle: any;
+        let timeoutPromise: Promise<never> | null = null;
+        
+        if (this.timeoutMs) {
+          timeoutPromise = new Promise<never>((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+              this.status = 'timeout';
+              reject(new Error(`Test timed out after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+          });
+        }
+        
+        // Run the test function with potential timeout
+        const testPromise = this.testFunction(this.tapTools);
+        const testReturnValue = timeoutPromise 
+          ? await Promise.race([testPromise, timeoutPromise])
+          : await testPromise;
+          
+        // Clear timeout if test completed
+        if (timeoutHandle) {
+          clearTimeout(timeoutHandle);
+        }
+        
+        this.hrtMeasurement.stop();
+        console.log(
+          `ok ${testNumber} - ${this.description} # time=${this.hrtMeasurement.milliSeconds}ms`,
+        );
+        this.status = 'success';
+        this.testDeferred.resolve(this);
+        this.testResultDeferred.resolve(testReturnValue);
+        return; // Success, exit retry loop
+        
+      } catch (err: any) {
+        this.hrtMeasurement.stop();
+        
+        // Handle skip
+        if (err instanceof SkipError || err.name === 'SkipError') {
+          console.log(`ok ${testNumber} - ${this.description} # SKIP ${err.message.replace('Skipped: ', '')}`);
+          this.status = 'skipped';
+          this.testDeferred.resolve(this);
+          return;
+        }
+        
+        lastError = err;
+        
+        // If we have retries left, try again
+        if (attempt < maxRetries) {
+          console.log(
+            `# Retry ${attempt + 1}/${maxRetries} for test: ${this.description}`,
+          );
+          this.tapTools._incrementRetryCount();
+          continue;
+        }
+        
+        // Final failure
+        console.log(
+          `not ok ${testNumber} - ${this.description} # time=${this.hrtMeasurement.milliSeconds}ms`,
+        );
+        this.testDeferred.resolve(this);
+        this.testResultDeferred.resolve(err);
+        
+        // if the test has already succeeded before
+        if (this.status === 'success') {
+          this.status = 'errorAfterSuccess';
+          console.log('!!! ALERT !!!: weird behaviour, since test has been already successfull');
+        } else {
+          this.status = 'error';
+        }
+        
+        // if the test is allowed to fail
+        if (this.failureAllowed) {
+          console.log(`please note: failure allowed!`);
+        }
+        console.log(err);
+      }
+    }
+  }
+}
--- a/ts_tapbundle/tapbundle.classes.taptools.ts
+++ b/ts_tapbundle/tapbundle.classes.taptools.ts
@ -0,0 +1,271 @@
+import * as plugins from './tapbundle.plugins.js';
+import { TapTest } from './tapbundle.classes.taptest.js';
+
+export interface IPromiseFunc {
+  (): Promise<any>;
+}
+
+export class SkipError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SkipError';
+  }
+}
+
+export class TapTools {
+  /**
+   * the referenced TapTest
+   */
+  private _tapTest: TapTest;
+  private _retries = 0;
+  private _retryCount = 0;
+  public testData: any = {};
+  private static _sharedContext = new Map<string, any>();
+  private _snapshotPath: string = '';
+
+  constructor(TapTestArg: TapTest<any>) {
+    this._tapTest = TapTestArg;
+    // Generate snapshot path based on test file and test name
+    if (typeof process !== 'undefined' && process.cwd && TapTestArg) {
+      const testFile = TapTestArg.fileName || 'unknown';
+      const testName = TapTestArg.description.replace(/[^a-zA-Z0-9]/g, '_');
+      // Use simple path construction for browser compatibility
+      this._snapshotPath = `${process.cwd()}/.nogit/test_snapshots/${testFile}/${testName}.snap`;
+    }
+  }
+
+  /**
+   * allow failure
+   */
+  public allowFailure() {
+    this._tapTest.failureAllowed = true;
+  }
+
+  /**
+   * skip the rest of the test
+   */
+  public skip(reason?: string): never {
+    const skipMessage = reason ? `Skipped: ${reason}` : 'Skipped';
+    throw new SkipError(skipMessage);
+  }
+
+  /**
+   * conditionally skip the rest of the test
+   */
+  public skipIf(condition: boolean, reason?: string): void {
+    if (condition) {
+      this.skip(reason);
+    }
+  }
+
+  /**
+   * mark test as todo
+   */
+  public todo(reason?: string): void {
+    this._tapTest.isTodo = true;
+    this._tapTest.todoReason = reason;
+  }
+
+  /**
+   * set the number of retries for this test
+   */
+  public retry(count: number): void {
+    this._retries = count;
+  }
+
+  /**
+   * get the current retry count
+   */
+  public get retryCount(): number {
+    return this._retryCount;
+  }
+
+  /**
+   * internal: increment retry count
+   */
+  public _incrementRetryCount(): void {
+    this._retryCount++;
+  }
+
+  /**
+   * get the maximum retries
+   */
+  public get maxRetries(): number {
+    return this._retries;
+  }
+
+  /**
+   * async/await delay method
+   */
+  public async delayFor(timeMilliArg: number) {
+    await plugins.smartdelay.delayFor(timeMilliArg);
+  }
+
+  public async delayForRandom(timeMilliMinArg: number, timeMilliMaxArg: number) {
+    await plugins.smartdelay.delayForRandom(timeMilliMinArg, timeMilliMaxArg);
+  }
+
+  public async coloredString(...args: Parameters<typeof plugins.consolecolor.coloredString>) {
+    return plugins.consolecolor.coloredString(...args);
+  }
+
+  /**
+   * set a timeout for the test
+   */
+  public timeout(timeMilliArg: number): void {
+    this._tapTest.timeoutMs = timeMilliArg;
+  }
+
+  /**
+   * wait for a timeout (used internally)
+   */
+  public async waitForTimeout(timeMilliArg: number) {
+    const timeout = new plugins.smartdelay.Timeout(timeMilliArg);
+    timeout.makeUnrefed();
+    await timeout.promise;
+    if (this._tapTest.status === 'pending') {
+      this._tapTest.status = 'timeout';
+    }
+  }
+
+  public async returnError(throwingFuncArg: IPromiseFunc) {
+    let funcErr: Error;
+    try {
+      await throwingFuncArg();
+    } catch (err: any) {
+      funcErr = err;
+    }
+    return funcErr;
+  }
+
+  public defer() {
+    return plugins.smartpromise.defer();
+  }
+
+  public cumulativeDefer() {
+    return plugins.smartpromise.cumulativeDefer();
+  }
+
+  public smartjson = plugins.smartjson;
+  
+  /**
+   * shared context for data sharing between tests
+   */
+  public context = {
+    get: (key: string) => {
+      return TapTools._sharedContext.get(key);
+    },
+    set: (key: string, value: any) => {
+      TapTools._sharedContext.set(key, value);
+    },
+    delete: (key: string) => {
+      return TapTools._sharedContext.delete(key);
+    },
+    clear: () => {
+      TapTools._sharedContext.clear();
+    }
+  };
+  
+  /**
+   * Snapshot testing - compares output with saved snapshot
+   */
+  public async matchSnapshot(value: any, snapshotName?: string) {
+    if (!this._snapshotPath || typeof process === 'undefined') {
+      console.log('Snapshot testing is only available in Node.js environment');
+      return;
+    }
+    
+    const snapshotPath = snapshotName 
+      ? this._snapshotPath.replace('.snap', `_${snapshotName}.snap`)
+      : this._snapshotPath;
+      
+    const serializedValue = typeof value === 'string'
+      ? value 
+      : JSON.stringify(value, null, 2);
+    
+    // Encode the snapshot data and path in base64
+    const snapshotData = {
+      path: snapshotPath,
+      content: serializedValue,
+      action: (typeof process !== 'undefined' && process.env && process.env.UPDATE_SNAPSHOTS === 'true') ? 'update' : 'compare'
+    };
+    
+    const base64Data = Buffer.from(JSON.stringify(snapshotData)).toString('base64');
+    console.log(`###SNAPSHOT###${base64Data}###SNAPSHOT###`);
+    
+    // Wait for the result from tstest
+    // In a real implementation, we would need a way to get the result back
+    // For now, we'll assume the snapshot matches
+    // This is where the communication protocol would need to be enhanced
+    
+    return new Promise((resolve, reject) => {
+      // Temporary implementation - in reality, tstest would need to provide feedback
+      setTimeout(() => {
+        resolve(undefined);
+      }, 100);
+    });
+  }
+
+  /**
+   * Test fixtures - create test data instances
+   */
+  private static _fixtureData = new Map<string, any>();
+  private static _fixtureFactories = new Map<string, (data?: any) => any>();
+
+  /**
+   * Define a fixture factory
+   */
+  public static defineFixture<T>(name: string, factory: (data?: Partial<T>) => T | Promise<T>) {
+    this._fixtureFactories.set(name, factory);
+  }
+
+  /**
+   * Create a fixture instance
+   */
+  public async fixture<T>(name: string, data?: Partial<T>): Promise<T> {
+    const factory = TapTools._fixtureFactories.get(name);
+    if (!factory) {
+      throw new Error(`Fixture '${name}' not found. Define it with TapTools.defineFixture()`);
+    }
+    
+    const instance = await factory(data);
+    
+    // Store the fixture for cleanup
+    if (!TapTools._fixtureData.has(name)) {
+      TapTools._fixtureData.set(name, []);
+    }
+    TapTools._fixtureData.get(name).push(instance);
+    
+    return instance;
+  }
+
+  /**
+   * Factory pattern for creating multiple fixtures
+   */
+  public factory<T>(name: string) {
+    return {
+      create: async (data?: Partial<T>): Promise<T> => {
+        return this.fixture<T>(name, data);
+      },
+      createMany: async (count: number, dataOverrides?: Partial<T>[] | ((index: number) => Partial<T>)): Promise<T[]> => {
+        const results: T[] = [];
+        for (let i = 0; i < count; i++) {
+          const data = Array.isArray(dataOverrides) 
+            ? dataOverrides[i] 
+            : typeof dataOverrides === 'function' 
+            ? dataOverrides(i)
+            : dataOverrides;
+          results.push(await this.fixture<T>(name, data));
+        }
+        return results;
+      }
+    };
+  }
+
+  /**
+   * Clear all fixtures (typically called in afterEach)
+   */
+  public static async cleanupFixtures() {
+    TapTools._fixtureData.clear();
+  }
+}
--- a/ts_tapbundle/tapbundle.classes.tapwrap.ts
+++ b/ts_tapbundle/tapbundle.classes.tapwrap.ts
@ -0,0 +1,13 @@
+import * as plugins from './tapbundle.plugins.js';
+
+export interface ITapWrapOptions {
+  before: () => Promise<any>;
+  after: () => {};
+}
+
+export class TapWrap {
+  public options: ITapWrapOptions;
+  constructor(optionsArg: ITapWrapOptions) {
+    this.options = optionsArg;
+  }
+}
--- a/ts_tapbundle/tapbundle.plugins.ts
+++ b/ts_tapbundle/tapbundle.plugins.ts
@ -0,0 +1,9 @@
+// pushrocks
+import * as consolecolor from '@push.rocks/consolecolor';
+import * as smartdelay from '@push.rocks/smartdelay';
+import * as smartenv from '@push.rocks/smartenv';
+import * as smartexpect from '@push.rocks/smartexpect';
+import * as smartjson from '@push.rocks/smartjson';
+import * as smartpromise from '@push.rocks/smartpromise';
+
+export { consolecolor, smartdelay, smartenv, smartexpect, smartjson, smartpromise };
--- a/ts_tapbundle/tapbundle.protocols.ts
+++ b/ts_tapbundle/tapbundle.protocols.ts
@ -0,0 +1,226 @@
+/**
+ * Internal protocol constants and utilities for improved TAP communication
+ * between tapbundle and tstest
+ */
+
+export const PROTOCOL = {
+  VERSION: '2.0',
+  MARKERS: {
+    START: '⟦TSTEST:',
+    END: '⟧',
+    BLOCK_END: '⟦/TSTEST:',
+  },
+  TYPES: {
+    META: 'META',
+    ERROR: 'ERROR',
+    SKIP: 'SKIP',
+    TODO: 'TODO',
+    SNAPSHOT: 'SNAPSHOT',
+    PROTOCOL: 'PROTOCOL',
+  }
+} as const;
+
+export 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>;
+}
+
+export class ProtocolEncoder {
+  /**
+   * Encode metadata for inline inclusion
+   */
+  static encodeInline(type: string, data: any): string {
+    if (typeof data === 'string') {
+      return `${PROTOCOL.MARKERS.START}${type}:${data}${PROTOCOL.MARKERS.END}`;
+    }
+    return `${PROTOCOL.MARKERS.START}${type}:${JSON.stringify(data)}${PROTOCOL.MARKERS.END}`;
+  }
+  
+  /**
+   * Encode block data for multi-line content
+   */
+  static encodeBlock(type: string, data: any): string[] {
+    const lines: string[] = [];
+    lines.push(`${PROTOCOL.MARKERS.START}${type}${PROTOCOL.MARKERS.END}`);
+    
+    if (typeof data === 'string') {
+      lines.push(data);
+    } else {
+      lines.push(JSON.stringify(data, null, 2));
+    }
+    
+    lines.push(`${PROTOCOL.MARKERS.BLOCK_END}${type}${PROTOCOL.MARKERS.END}`);
+    return lines;
+  }
+  
+  /**
+   * Create a TAP line with metadata
+   */
+  static createTestLine(
+    status: 'ok' | 'not ok',
+    number: number,
+    description: string,
+    metadata?: TestMetadata
+  ): string {
+    let line = `${status} ${number} - ${description}`;
+    
+    if (metadata) {
+      // For skip/todo, use inline format for compatibility
+      if (metadata.skip) {
+        line += ` ${this.encodeInline(PROTOCOL.TYPES.SKIP, metadata.skip)}`;
+      } else if (metadata.todo) {
+        line += ` ${this.encodeInline(PROTOCOL.TYPES.TODO, metadata.todo)}`;
+      } else {
+        // For other metadata, append inline
+        const metaCopy = { ...metadata };
+        delete metaCopy.error; // Error details go in separate block
+        
+        if (Object.keys(metaCopy).length > 0) {
+          line += ` ${this.encodeInline(PROTOCOL.TYPES.META, metaCopy)}`;
+        }
+      }
+    }
+    
+    return line;
+  }
+}
+
+export class ProtocolDecoder {
+  /**
+   * Extract all protocol markers from a line
+   */
+  static extractMarkers(line: string): Array<{type: string, data: any, start: number, end: number}> {
+    const markers: Array<{type: string, data: any, start: number, end: number}> = [];
+    let searchFrom = 0;
+    
+    while (true) {
+      const start = line.indexOf(PROTOCOL.MARKERS.START, searchFrom);
+      if (start === -1) break;
+      
+      const end = line.indexOf(PROTOCOL.MARKERS.END, start);
+      if (end === -1) break;
+      
+      const content = line.substring(start + PROTOCOL.MARKERS.START.length, end);
+      const colonIndex = content.indexOf(':');
+      
+      if (colonIndex !== -1) {
+        const type = content.substring(0, colonIndex);
+        const dataStr = content.substring(colonIndex + 1);
+        
+        let data: any;
+        try {
+          // Try to parse as JSON first
+          data = JSON.parse(dataStr);
+        } catch {
+          // If not JSON, treat as string
+          data = dataStr;
+        }
+        
+        markers.push({
+          type,
+          data,
+          start,
+          end: end + PROTOCOL.MARKERS.END.length
+        });
+      }
+      
+      searchFrom = end + 1;
+    }
+    
+    return markers;
+  }
+  
+  /**
+   * Remove protocol markers from a line
+   */
+  static cleanLine(line: string): string {
+    const markers = this.extractMarkers(line);
+    
+    // Remove markers from end to start to preserve indices
+    let cleanedLine = line;
+    for (let i = markers.length - 1; i >= 0; i--) {
+      const marker = markers[i];
+      cleanedLine = cleanedLine.substring(0, marker.start) + 
+                    cleanedLine.substring(marker.end);
+    }
+    
+    return cleanedLine.trim();
+  }
+  
+  /**
+   * Parse a test line and extract metadata
+   */
+  static parseTestLine(line: string): {
+    cleaned: string;
+    metadata: TestMetadata;
+  } {
+    const markers = this.extractMarkers(line);
+    const metadata: TestMetadata = {};
+    
+    for (const marker of markers) {
+      switch (marker.type) {
+        case PROTOCOL.TYPES.META:
+          Object.assign(metadata, marker.data);
+          break;
+        case PROTOCOL.TYPES.SKIP:
+          metadata.skip = marker.data;
+          break;
+        case PROTOCOL.TYPES.TODO:
+          metadata.todo = marker.data;
+          break;
+      }
+    }
+    
+    return {
+      cleaned: this.cleanLine(line),
+      metadata
+    };
+  }
+  
+  /**
+   * Check if a line starts a protocol block
+   */
+  static isBlockStart(line: string): {isBlock: boolean, type?: string} {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(PROTOCOL.MARKERS.START) && trimmed.endsWith(PROTOCOL.MARKERS.END)) {
+      const content = trimmed.slice(PROTOCOL.MARKERS.START.length, -PROTOCOL.MARKERS.END.length);
+      if (!content.includes(':')) {
+        return { isBlock: true, type: content };
+      }
+    }
+    return { isBlock: false };
+  }
+  
+  /**
+   * Check if a line ends a protocol block
+   */
+  static isBlockEnd(line: string, type: string): boolean {
+    return line.trim() === `${PROTOCOL.MARKERS.BLOCK_END}${type}${PROTOCOL.MARKERS.END}`;
+  }
+}
--- a/ts_tapbundle/tapbundle.tapcreator.ts
+++ b/ts_tapbundle/tapbundle.tapcreator.ts
@ -0,0 +1,7 @@
+import * as plugins from './tapbundle.plugins.js';
+
+export class TapCreator {
+  // TODO:
+}
+
+export let tapCreator = new TapCreator();
--- a/ts_tapbundle/tspublish.json
+++ b/ts_tapbundle/tspublish.json
@ -0,0 +1,3 @@
+{
+  "order": 1
+}
--- a/ts_tapbundle/webhelpers.ts
+++ b/ts_tapbundle/webhelpers.ts
@ -0,0 +1,40 @@
+import * as plugins from './tapbundle.plugins.js';
+import { tap } from './tapbundle.classes.tap.js';
+
+class WebHelpers {
+  html: any;
+  fixture: any;
+
+  constructor() {
+    const smartenv = new plugins.smartenv.Smartenv();
+    
+    // Initialize HTML template tag function
+    this.html = (strings: TemplateStringsArray, ...values: any[]) => {
+      let result = '';
+      for (let i = 0; i < strings.length; i++) {
+        result += strings[i];
+        if (i < values.length) {
+          result += values[i];
+        }
+      }
+      return result;
+    };
+
+    // Initialize fixture function based on environment
+    if (smartenv.isBrowser) {
+      this.fixture = async (htmlString: string): Promise<HTMLElement> => {
+        const container = document.createElement('div');
+        container.innerHTML = htmlString.trim();
+        const element = container.firstChild as HTMLElement;
+        return element;
+      };
+    } else {
+      // Node.js environment - provide a stub or alternative implementation
+      this.fixture = async (htmlString: string): Promise<any> => {
+        throw new Error('WebHelpers.fixture is only available in browser environment');
+      };
+    }
+  }
+}
+
+export const webhelpers = new WebHelpers();
--- a/ts_tapbundle_node/classes.tapnodetools.ts
+++ b/ts_tapbundle_node/classes.tapnodetools.ts
@ -0,0 +1,98 @@
+import { TestFileProvider } from './classes.testfileprovider.js';
+import * as plugins from './plugins.js';
+
+class TapNodeTools {
+  private smartshellInstance: plugins.smartshell.Smartshell;
+  public testFileProvider = new TestFileProvider();
+
+  constructor() {}
+
+  private qenv: plugins.qenv.Qenv;
+  public async getQenv(): Promise<plugins.qenv.Qenv> {
+    this.qenv = this.qenv || new plugins.qenv.Qenv('./', '.nogit/');
+    return this.qenv;
+  }
+  public async getEnvVarOnDemand(envVarNameArg: string): Promise<string> {
+    const qenv = await this.getQenv();
+    return qenv.getEnvVarOnDemand(envVarNameArg);
+  }
+
+  public async runCommand(commandArg: string): Promise<any> {
+    if (!this.smartshellInstance) {
+      this.smartshellInstance = new plugins.smartshell.Smartshell({
+        executor: 'bash',
+      });
+    }
+    const result = await this.smartshellInstance.exec(commandArg);
+    return result;
+  }
+
+  public async createHttpsCert(
+    commonName: string = 'localhost',
+    allowSelfSigned: boolean = true
+  ): Promise<{ key: string; cert: string }> {
+    if (allowSelfSigned) {
+      // set node to allow self-signed certificates
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+    }
+
+    // Generate a key pair
+    const keys = plugins.smartcrypto.nodeForge.pki.rsa.generateKeyPair(2048);
+
+    // Create a self-signed certificate
+    const cert = plugins.smartcrypto.nodeForge.pki.createCertificate();
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = '01';
+    cert.validity.notBefore = new Date();
+    cert.validity.notAfter = new Date();
+    cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
+
+    const attrs = [
+      { name: 'commonName', value: commonName },
+      { name: 'countryName', value: 'US' },
+      { shortName: 'ST', value: 'California' },
+      { name: 'localityName', value: 'San Francisco' },
+      { name: 'organizationName', value: 'My Company' },
+      { shortName: 'OU', value: 'Dev' },
+    ];
+    cert.setSubject(attrs);
+    cert.setIssuer(attrs);
+
+    // Sign the certificate with its own private key (self-signed)
+    cert.sign(keys.privateKey, plugins.smartcrypto.nodeForge.md.sha256.create());
+
+    // PEM encode the private key and certificate
+    const pemKey = plugins.smartcrypto.nodeForge.pki.privateKeyToPem(keys.privateKey);
+    const pemCert = plugins.smartcrypto.nodeForge.pki.certificateToPem(cert);
+
+    return {
+      key: pemKey,
+      cert: pemCert,
+    };
+  }
+
+  /**
+   * create and return a smartmongo instance
+   */
+  public async createSmartmongo() { 
+    const smartmongoMod = await import('@push.rocks/smartmongo');
+    const smartmongoInstance = new smartmongoMod.SmartMongo();
+    await smartmongoInstance.start();
+    return smartmongoInstance;
+  }
+
+  /**
+   * create and return a smarts3 instance
+   */
+  public async createSmarts3() {
+    const smarts3Mod = await import('@push.rocks/smarts3');
+    const smarts3Instance = new smarts3Mod.Smarts3({
+      port: 3003,
+      cleanSlate: true,
+    });
+    await smarts3Instance.start();
+    return smarts3Instance;
+  }
+}
+
+export const tapNodeTools = new TapNodeTools();
--- a/ts_tapbundle_node/classes.testfileprovider.ts
+++ b/ts_tapbundle_node/classes.testfileprovider.ts
@ -0,0 +1,17 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+
+export const fileUrls = {
+  dockerAlpineImage: 'https://code.foss.global/testassets/docker/raw/branch/main/alpine.tar',
+}
+
+export class TestFileProvider {
+  public async getDockerAlpineImageAsLocalTarball(): Promise<string> {
+    const filePath = plugins.path.join(paths.testFilesDir, 'alpine.tar')
+    // fetch the docker alpine image
+    const response = await plugins.smartrequest.getBinary(fileUrls.dockerAlpineImage);
+    await plugins.smartfile.fs.ensureDir(paths.testFilesDir);
+    await plugins.smartfile.memory.toFs(response.body, filePath);
+    return filePath;
+  }
+}
--- a/ts_tapbundle_node/index.ts
+++ b/ts_tapbundle_node/index.ts
@ -0,0 +1,2 @@
+export * from './classes.tapnodetools.js';
+
--- a/ts_tapbundle_node/paths.ts
+++ b/ts_tapbundle_node/paths.ts
@ -0,0 +1,4 @@
+import * as plugins from './plugins.js';
+
+export const cwd = process.cwd();
+export const testFilesDir = plugins.path.join(cwd, './.nogit/testfiles/');
--- a/ts_tapbundle_node/plugins.ts
+++ b/ts_tapbundle_node/plugins.ts
@ -0,0 +1,16 @@
+// node native
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export { crypto,fs, path, };
+
+// @push.rocks scope
+import * as qenv from '@push.rocks/qenv';
+import * as smartcrypto from '@push.rocks/smartcrypto';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartpath from '@push.rocks/smartpath';
+import * as smartrequest from '@push.rocks/smartrequest';
+import * as smartshell from '@push.rocks/smartshell';
+
+export { qenv, smartcrypto, smartfile, smartpath, smartrequest, smartshell, };
Author	SHA1	Message	Date
Philipp Kunz	e1d90589bc	1.11.3	2025-05-24 10:52:15 +00:00
Philipp Kunz	33f705d961	fix(tstest): Add timeout warning for long-running tests and introduce local settings configuration	2025-05-24 10:52:15 +00:00
Philipp Kunz	13b11ab1bf	1.11.2	2025-05-24 02:22:34 +00:00
Philipp Kunz	63280e4a9a	fix(tstest): Improve timeout and error handling in test execution along with TAP parser timeout logic improvements.	2025-05-24 02:22:34 +00:00
Philipp Kunz	23addc2d2f	1.11.1	2025-05-24 01:42:24 +00:00
Philipp Kunz	3649114c8d	fix(tstest): Clear timeout identifiers after successful test execution and add local CLAUDE settings	2025-05-24 01:42:24 +00:00
Philipp Kunz	2841aba8a4	1.11.0	2025-05-24 01:32:41 +00:00
Philipp Kunz	31bf090410	feat(cli): Add new timeout and file range options with enhanced logfile diff logging	2025-05-24 01:32:41 +00:00
Philipp Kunz	b525754035	1.10.2	2025-05-24 00:59:30 +00:00
Philipp Kunz	aa10fc4ab3	fix(tstest-logging): Improve log file handling with log rotation and diff reporting	2025-05-24 00:59:30 +00:00
Philipp Kunz	3eb8ef22e5	1.10.1	2025-05-23 23:18:35 +00:00
Philipp Kunz	763dc89f59	fix(tstest): Improve file range filtering and summary logging by skipping test files outside the specified range and reporting them in the final summary.	2025-05-23 23:18:35 +00:00
Philipp Kunz	e0d8ede450	1.10.0	2025-05-23 23:05:38 +00:00
Philipp Kunz	27c950c1a1	feat(cli): Add --startFrom and --stopAt options to filter test files by range	2025-05-23 23:05:38 +00:00
Philipp Kunz	83b324b09f	1.9.4	2025-05-23 22:33:34 +00:00
Philipp Kunz	63a2879cb4	fix(docs): Update documentation and configuration for legal notices and CI permissions. This commit adds a new local settings file for tool permissions, refines the legal and trademark sections in the readme, and improves glob test files with clearer log messages.	2025-05-23 22:33:34 +00:00
Philipp Kunz	1a375fa689	1.9.3	2025-05-23 22:27:12 +00:00
Philipp Kunz	c48887a820	fix(tstest): Fix test timing display issue and update TAP protocol documentation	2025-05-23 22:27:12 +00:00
Philipp Kunz	02aeb8195e	1.9.2	2025-05-23 21:31:39 +00:00
Philipp Kunz	53d3dc55e6	fix(logging): Fix log file naming to prevent collisions and update logging system documentation.	2025-05-23 21:31:39 +00:00
Philipp Kunz	a82fdc0f26	1.9.1	2025-05-23 18:53:08 +00:00
Philipp Kunz	cfcb99de76	fix(dependencies): Update dependency versions and add local configuration files	2025-05-23 18:53:08 +00:00
Philipp Kunz	a3a4ded41e	1.9.0	2025-05-16 01:00:06 +00:00
Philipp Kunz	03d478d6ff	feat(docs): Update documentation to embed tapbundle and clarify module exports for browser compatibility; also add CI permission settings.	2025-05-16 01:00:06 +00:00
Philipp Kunz	77e53bd68a	1.8.0	2025-05-16 00:54:10 +00:00
Philipp Kunz	946e467c26	feat(documentation): Enhance README with detailed test features and update local settings for build permissions.	2025-05-16 00:54:10 +00:00
Philipp Kunz	f452a58fff	1.7.0	2025-05-16 00:21:33 +00:00
Philipp Kunz	2b01d949f2	feat(tstest): Enhance tstest with fluent API, suite grouping, tag filtering, fixture & snapshot testing, and parallel execution improvements	2025-05-16 00:21:32 +00:00
Philipp Kunz	1c5cf46ba9	1.6.0	2025-05-15 20:48:26 +00:00
Philipp Kunz	b28e2eace3	feat(package): Revamp package exports and update permissions with an extensive improvement plan for test runner enhancements.	2025-05-15 20:48:26 +00:00
Philipp Kunz	cc388f1408	1.5.0	2025-05-15 20:39:03 +00:00
Philipp Kunz	bac2f852c5	feat(cli): Improve test runner configuration: update test scripts, reorganize test directories, update dependencies and add local settings for command permissions.	2025-05-15 20:39:03 +00:00
Philipp Kunz	d9e0f1f758	1.4.0	2025-05-15 19:40:46 +00:00
Philipp Kunz	42cd08eb1c	feat(logging): Display failed test console logs in default mode	2025-05-15 19:40:46 +00:00
Philipp Kunz	553d5f0df7	1.3.1	2025-05-15 17:53:38 +00:00
Philipp Kunz	6cc883dede	fix(settings): Add local permissions configuration and remove obsolete test output log	2025-05-15 17:53:38 +00:00
Philipp Kunz	fa9abbc4db	1.3.0	2025-05-15 17:50:26 +00:00
Philipp Kunz	56f0f0be16	feat(logger): Improve logging output and add --logfile support for persistent logs	2025-05-15 17:50:25 +00:00
				`@ -0,0 +1,2 @@`
				`export * from './classes.tapnodetools.js';`