5.6.3

.gitea/workflows/default_nottags.yaml

@@ -6,8 +6,8 @@ on:
       - '**'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
+  IMAGE: code.foss.global/hosttoday/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
   NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
   NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
   NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
@@ -26,7 +26,7 @@ jobs:
       - name: Install pnpm and npmci
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
 
       - name: Run npm prepare
         run: npmci npm prepare

.gitea/workflows/default_tags.yaml

@@ -6,8 +6,8 @@ on:
       - '*'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
+  IMAGE: code.foss.global/hosttoday/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
   NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
   NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
   NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
@@ -26,7 +26,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Audit production dependencies
@@ -54,7 +54,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Test stable
@@ -82,7 +82,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Release
@@ -104,7 +104,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Code quality

changelog.md

@@ -1,5 +1,191 @@
 # Changelog
 
+## 2025-04-08 - 5.6.3 - fix(package.json)
+Update dependency versions for smartmongo, smartrequest, tsbuild, and @types/node
+
+- Bump @push.rocks/smartmongo from 2.0.10 to 2.0.12
+- Bump @push.rocks/smartrequest from 2.0.23 to 2.1.0
+- Bump @git.zone/tsbuild from 2.2.6 to 2.3.2
+- Bump @types/node from 22.13.10 to 22.14.0
+
+## 2025-04-02 - 5.6.2 - fix(package.json)
+Fix formatting in package.json to correctly include the packageManager field
+
+- Added missing comma after the keywords array
+- Ensured proper inclusion of the packageManager field for consistency
+
+## 2025-04-02 - 5.6.1 - fix(readme)
+Update README: Revamp structure for features, installation, and examples
+
+- Reorganized sections to highlight features, installation, core API, and getting started
+- Updated code examples for clarity, including Node integration and web testing sections
+- Standardized headings and removed extraneous documentation details
+
+## 2025-03-17 - 5.6.0 - feat(tap)
+Add explicit fail method to the Tap class for better test failure handling
+
+- Introduced fail() method that throws a custom error message to explicitly mark test failures
+- Improves clarity in test flow by giving developers a direct way to trigger error states
+
+## 2025-03-08 - 5.5.10 - fix(node)
+Removed unused jest dependency from project.
+
+- Removed '@jest/globals' from dependencies in package.json.
+- Removed unused jest import from ts_node/index.ts.
+- Kept 'expect' dependency from jest library.
+
+## 2025-03-08 - 5.5.9 - fix(dependencies)
+Fix missing jest dependency in package.json and update exports in ts_node/index.ts
+
+- Added missing '@jest/globals' dependency to package.json.
+- Updated ts_node/index.ts to properly export jest along with jestExpect.
+
+## 2025-03-08 - 5.5.8 - fix(test)
+Ensure compatibility with async/await in test cases.
+
+
+## 2025-03-08 - 5.5.7 - fix(dependencies)
+Updated project dependencies to the latest versions for improved stability and performance.
+
+- Updated `@push.rocks/smartexpect` to version 1.6.1.
+- Updated `@push.rocks/smartfile` to version 11.2.0.
+- Updated `@push.rocks/smartpromise` to version 4.2.3.
+- Updated `@push.rocks/smartshell` to version 3.2.3.
+- Updated `@git.zone/tsbuild` to version 2.2.6.
+- Updated `@git.zone/tstest` to version 1.0.96.
+- Updated `@types/node` to version 22.13.10.
+
+## 2025-01-19 - 5.5.6 - fix(dependencies)
+Update smartpromise dependency to version 4.2.0.
+
+- Updated @push.rocks/smartpromise dependency from version 4.1.0 to 4.2.0 in package.json.
+
+## 2025-01-19 - 5.5.5 - fix(dependencies)
+Update dependencies to the latest versions to address multiple fixes.
+
+- Updated @push.rocks/smartexpect to version ^1.4.0.
+- Updated @push.rocks/smartfile to version ^11.1.5.
+- Updated @push.rocks/smartpromise to version ^4.1.0.
+- Updated @types/node to version ^22.10.7.
+- Updated randomstring to version ^1.3.1.
+
+## 2024-12-30 - 5.5.4 - fix(dependencies)
+Update package dependencies to their latest versions.
+
+- Updated @push.rocks/smartexpect from ^1.2.1 to ^1.3.0.
+- Updated @push.rocks/smartfile from ^11.0.21 to ^11.0.23.
+- Updated @push.rocks/smartshell from ^3.0.6 to ^3.2.2.
+- Updated @push.rocks/smarttime from ^4.0.8 to ^4.1.1.
+- Updated @types/node from ^22.9.3 to ^22.10.2.
+
+## 2024-11-23 - 5.5.3 - fix(docs)
+Update description and keywords in package files for clarity
+
+- Updated project description in package.json and npmextra.json for better clarity.
+- Enhanced keywords list in package.json and npmextra.json to cover more relevant topics.
+- Revised README.md content to provide a more comprehensive usage guide and correct mismatched sections.
+
+## 2024-11-23 - 5.5.2 - fix(core)
+Apply code cleanup and refactoring.
+
+
+## 2024-11-23 - 5.5.1 - fix(core)
+Update dependencies and add jestExpect export
+
+- Updated '@push.rocks/qenv' to '^6.1.0' in dependencies.
+- Updated 'expect' package version to '^29.7.0' in dependencies.
+- Updated '@types/node' to '^22.9.3' in devDependencies.
+- Added jestExpect export in ts_node/index.ts.
+
+## 2024-11-06 - 5.5.0 - feat(tapnodetools)
+Add TestFileProvider for handling Docker Alpine image
+
+- Introduced TestFileProvider in TapNodeTools.
+- Added method to retrieve Docker Alpine image as a local tarball.
+
+## 2024-11-06 - 5.4.4 - fix(dependencies)
+Update smarts3 dependency to version 2.2.5
+
+
+## 2024-11-06 - 5.4.3 - fix(TapNodeTools)
+Fix server port default value in createSmarts3 method
+
+- The `createSmarts3` method in `TapNodeTools` now explicitly sets the port to 3003.
+
+## 2024-11-06 - 5.4.2 - fix(dependencies)
+Update smarts3 dependency version to fix issues.
+
+- Changed the version of @push.rocks/smarts3 from ^2.2.1 to ^2.2.2.
+
+## 2024-11-06 - 5.4.1 - fix(ci)
+Fix CI configuration URL and package installation paths.
+
+- Updated Docker image URL in CI config.
+- Fixed repository URL format in package.json.
+- Corrected npmci package installation path.
+
+## 2024-11-06 - 5.4.0 - feat(node)
+Add smartmongo and smarts3 integration in node tools
+
+- Added createSmartmongo method to TapNodeTools for creating SmartMongo instances.
+- Added createSmarts3 method to TapNodeTools for creating Smarts3 instances.
+- Updated dependencies with smartmongo and smarts3 in package.json.
+
+## 2024-09-19 - 5.3.0 - feat(TapNodeTools)
+Add getEnvVarOnDemand method to TapNodeTools
+
+- Introduced a new method getEnvVarOnDemand to the TapNodeTools class to fetch environment variables on demand.
+- Enhanced getQenv function in TapNodeTools class to cache the Qenv instance for better performance.
+
+## 2024-09-19 - 5.2.2 - fix(core)
+Ensure reliability in test setup and execution
+
+- Added new pre-task functionality to log starting of tasks.
+- Enhanced `runCommand` method to better handle shell command execution.
+- Fixed issue in `createHttpsCert` to correctly generate self-signed certificates.
+
+## 2024-09-19 - 5.2.1 - fix(tapbundle)
+Add qenv package to dependencies for environment management
+
+- Added @push.rocks/qenv to dependencies in package.json.
+- Updated TapNodeTools class in ts_node/classes.tapnodetools.ts to include getQenv method.
+- Imported qenv in ts_node/plugins.ts.
+
+## 2024-09-18 - 5.2.0 - feat(TapNodeTools)
+Add ability to create HTTPS certificates with self-signed option
+
+- Introduced a new parameter `allowSelfSigned` to the `createHttpsCert` function.
+
+## 2024-09-18 - 5.1.4 - fix(ts_node)
+Fixed issues in HTTPS certificate generation for TapNodeTools
+
+- Updated 'createHttpsCert' method in 'TapNodeTools' to use 'smartcrypto' for generating RSA key pair and self-signed certificate.
+- Corrected certificate and private key PEM encoding.
+
+## 2024-09-18 - 5.1.3 - fix(ts_node/classes.tapnodetools.ts)
+Refactored methods and improved type annotations in TapNodeTools class.
+
+- Refactored `runCommand` method to include proper type annotations.
+- Enhanced `createHttpsCert` method with proper type annotations and key generation logic.
+- Introduced `generateSelfSignedCert` method for better code organization and readability.
+
+## 2024-09-18 - 5.1.2 - fix(TapNodeTools)
+Default parameter added to createHttpsCert method
+
+- Updated createHttpsCert method to provide a default value for the parameter commonName.
+
+## 2024-09-18 - 5.1.1 - fix(ts_node)
+Fixed createHttpsCert interface
+
+- Removed unnecessary keyFile and certFile parameters from createHttpsCert method.
+
+## 2024-09-18 - 5.1.0 - feat(ts_node)
+Add support for HTTPS certificate creation
+
+- Added TapNodeTools class with methods to run commands and create HTTPS certificates
+- Exported necessary plugins including crypto and fs for node
+- Updated test cases to include tests for HTTPS certificate creation
+
 ## 2024-09-17 - 5.0.25 - fix(core)
 Fix typos in package.json, update dependencies and update workflow.
 

npmextra.json

@@ -14,22 +14,32 @@
       "githost": "code.foss.global",
       "gitscope": "push.rocks",
       "gitrepo": "tapbundle",
-      "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.",
+      "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.",
       "npmPackagename": "@push.rocks/tapbundle",
       "license": "MIT",
       "keywords": [
         "testing",
         "automation",
         "TAP",
-        "test anything protocol",
+        "Test Anything Protocol",
         "unit testing",
         "integration testing",
-        "JavaScript",
         "TypeScript",
+        "JavaScript",
         "test runner",
         "test framework",
         "web helpers",
-        "test utilities"
+        "test utilities",
+        "asynchronous testing",
+        "environment variables",
+        "crypto",
+        "shell commands",
+        "Node.js",
+        "cloud storage",
+        "browser testing",
+        "UI components",
+        "parallel testing",
+        "test lifecycle management"
       ]
     }
   },

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@push.rocks/tapbundle",
   "private": false,
-  "version": "5.0.25",
+  "version": "5.6.3",
-  "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.",
+  "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.",
   "exports": {
     ".": "./dist_ts/index.js",
     "./node": "./dist_ts_node/index.js"
@@ -15,31 +15,39 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://code.foss.global/push.rocks/tapbundle.git"
+    "url": "git+https://code.foss.global/push.rocks/tapbundle.git"
   },
   "author": "Lossless GmbH",
   "license": "MIT",
   "bugs": {
-    "url": "https://gitlab.com/pushrocks/tapbundle/issues"
+    "url": "https://code.foss.global/push.rocks/tapbundle/issues"
   },
-  "homepage": "https://code.foss.global/push.rocks/tapbundle",
+  "homepage": "https://code.foss.global/push.rocks/tapbundle#readme",
   "dependencies": {
     "@open-wc/testing": "^4.0.0",
     "@push.rocks/consolecolor": "^2.0.2",
+    "@push.rocks/qenv": "^6.1.0",
+    "@push.rocks/smartcrypto": "^2.0.4",
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartenv": "^5.0.12",
-    "@push.rocks/smartexpect": "^1.2.1",
+    "@push.rocks/smartexpect": "^1.6.1",
+    "@push.rocks/smartfile": "^11.2.0",
     "@push.rocks/smartjson": "^5.0.20",
-    "@push.rocks/smartpromise": "^4.0.4",
+    "@push.rocks/smartmongo": "^2.0.12",
-    "@push.rocks/smartshell": "^3.0.6",
+    "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smarttime": "^4.0.8"
+    "@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/smarttime": "^4.1.1",
+    "expect": "^29.7.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.66",
+    "@git.zone/tsbuild": "^2.3.2",
     "@git.zone/tsrun": "^1.2.43",
-    "@git.zone/tstest": "^1.0.77",
+    "@git.zone/tstest": "^1.0.96",
-    "@types/node": "^22.5.5",
+    "@types/node": "^22.14.0",
-    "randomstring": "^1.3.0"
+    "randomstring": "^1.3.1"
   },
   "files": [
     "ts/**/*",
@@ -60,14 +68,25 @@
     "testing",
     "automation",
     "TAP",
-    "test anything protocol",
+    "Test Anything Protocol",
     "unit testing",
     "integration testing",
-    "JavaScript",
     "TypeScript",
+    "JavaScript",
     "test runner",
     "test framework",
     "web helpers",
-    "test utilities"
+    "test utilities",
-  ]
+    "asynchronous testing",
+    "environment variables",
+    "crypto",
+    "shell commands",
+    "Node.js",
+    "cloud storage",
+    "browser testing",
+    "UI components",
+    "parallel testing",
+    "test lifecycle management"
+  ],
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
 }

readme.md

@@ -1,122 +1,179 @@
 # @push.rocks/tapbundle
-tap bundled for tapbuffer
 
-## Install
+A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.
-Install the package by running the following command in your terminal:
+
+## Features
+
+- TAP (Test Anything Protocol) compliant output
+- Support for both browser and Node.js environments
+- Built-in test coordination and timing measurements
+- Parallel and sequential test execution
+- Pre-task support for setup operations
+- Rich assertion library via `expect`
+- Comprehensive Node.js tooling (shell, crypto, MongoDB, S3)
+
+## Installation
 
 ```bash
 npm install @push.rocks/tapbundle --save-dev
 ```
 
-This will add `@push.rocks/tapbundle` to your project's `devDependencies`.
-
 ## Usage
-The `@push.rocks/tapbundle` package is a tap-compatible testing framework written in TypeScript, intended for use with tapbuffer. It includes a range of useful features enabling easy setup and execution of tests, assertion handling through `expect` and `expectAsync`, as well as auxiliary tools for delay and colored console output.
+
+The `@push.rocks/tapbundle` is a versatile testing framework compatible with TAP, designed using TypeScript to facilitate robust and scalable testing of applications, whether you are dealing with unit tests, integration tests, or simply need a streamlined way to automate assertions across your application's lifecycle. The framework is especially useful if you are already using or planning to use tapbuffer.
+
+### Core API
+
+The main test runner is accessed through the `tap` object:
+
+```typescript
+tap.test(
+  description: string,           // Test description
+  testFunction: async (tools?: TapTools) => Promise<any>,  // Test implementation
+  modeArg: 'normal' | 'only' | 'skip' = 'normal'          // Execution mode
+): TapTest
+```
 
 ### Getting Started
-First, ensure your project is set up with Typescript and supports ESM syntax. You can then import `tap`, `expect`, and `expectAsync` from `@push.rocks/tapbundle` to start defining your tests.
 
-```typescript
+1. **Basic Setup**
-import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
-```
 
-Here is a simple test example:
+   First, import the necessary modules:
 
-```typescript
+   ```typescript
-import { tap, expect } from '@push.rocks/tapbundle';
+   import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
+   ```
 
-tap.test('should succeed on true assertion', async () => {
+   Start with a simple test:
-  return expect(true).toBeTrue();
-});
 
-tap.start();
+   ```typescript
-```
+   tap.test('Initial test succeeds', async () => {
+     return expect(true).toBeTrue();
+   });
 
-### Defining Tests
+   tap.start();
-You can define tests with descriptions and async functions. The `tap` instance manages test execution, supports test skipping, and managing exclusive tests with the `.only` modifier.
+   ```
 
-```typescript
+2. **Defining and Organizing Tests**
-const myTest = tap.test('expect true to be true', async () => {
-  expect(true).toBeTrue();
-});
 
-const skippedTest = tap.skip.test('this test is skipped', async () => {
+   ```typescript
-  // This will not be executed
+   tap.test('basic arithmetic test', async () => {
-});
+     expect(1 + 1).toEqual(2);
+   });
 
-tap.only.test('only this test will run', async () => {
+   // Async Tests
-  expect('TapBundle').toContainString('Tap');
+   tap.test('async operation test', async () => {
-});
+     const fetchData = async () => Promise.resolve('data');
+     await expectAsync(fetchData()).toBeResolved();
+   });
+   ```
 
-tap.start();
+3. **Tools for Advanced Testing**
-```
 
-### Using `expect` and `expectAsync`
+   ```typescript
-The package provides `expect` and `expectAsync` for assertions:
+   // Delay and Timing
+   tap.test('test with delay', async (tools) => {
+     await tools.delayFor(500); // waits for 500ms
+     expect(true).toBeTrue();
+   });
 
-```typescript
+   // Custom Pre Tasks
-await expectAsync(Promise.resolve(true)).toBeResolved();
+   tap.preTask('initialize environment', async () => {
-expect(5).toBeGreaterThan(2);
+     console.log('Setting up preconditions');
-```
+   });
+   ```
 
-### Handling Asynchronous Operations
+4. **Execution Control**
-`tapbundle` facilitates working with async operations in tests. You can introduce delays or set timeouts:
 
-```typescript
+   ```typescript
-tap.test('async operation with delay', async (tools) => {
+   // Skip tests
-  await tools.delayFor(2000); // Wait for 2000 milliseconds
+   tap.skip.test('skip this test', async () => {
-  expect(true).toBeTrue();
+     // This test will be ignored
-});
+   });
 
-tap.start();
+   // Exclusive tests
-```
+   tap.only.test('run this test exclusively', async () => {
+     // Only this test will run
+   });
 
-### Advanced Usage
+   // Colored output
-#### Pre Tasks
+   tap.test('test with colored output', async (tools) => {
-You can define tasks to run before test execution begins:
+     const message = await tools.coloredString('Test Passed!', 'green');
+     console.log(message);
+   });
+   ```
 
-```typescript
+5. **Node.js Integration**
-tap.preTask('setup database', async () => {
-  // Perform setup here
-});
 
-tap.test('test database connection', async () => {
+   ```typescript
-  // Test the setup
+   import { tapNodeTools } from '@push.rocks/tapbundle/node';
-});
 
-tap.start();
+   tap.test('execute shell command', async () => {
-```
+     const result = await tapNodeTools.runCommand('ls -la');
+     expect(result.exitCode).toEqual(0);
+   });
 
-#### Accessing Test Metadata
+   tap.test('create HTTPS certificate', async () => {
-Each test returns a `TapTest` instance, from which you can access metadata and manipulate test behavior:
+     const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
+     expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----');
+   });
+   ```
 
-```typescript
+6. **Environment Variables**
-const test = tap.test('metadata example', async (tools) => {
-  tools.allowFailure();
-  expect(true).toBeTrue();
-});
 
-tap.start().then(() => {
+   ```typescript
-  console.log(`Test duration: ${test.hrtMeasurement.milliSeconds}ms`);
+   tap.test('use environment variable', async (tools) => {
-});
+     const dbUrl = await tools.getEnvVarOnDemand('DB_URL');
-```
+     expect(dbUrl).toBeDefined();
+   });
+   ```
 
-### Running Tests
+7. **Asynchronous Control**
-Tests are executed by calling `tap.start()`. This method runs all defined tests in sequence and respects `.skip` and `.only` modifiers.
 
-### Debugging and Output
+   ```typescript
-`@push.rocks/tapbundle` supports colored console output via `consolecolor` to help with debugging and test result readability:
+   tap.test('controlled async scenario', async (tools) => {
+     const asyncOp = async () => Promise.resolve('complete');
+     tools.timeout(1000); // if operation exceeds 1000ms, test fails
+     const result = await asyncOp();
+     expect(result).toBe('complete');
+   });
+   ```
 
-```typescript
+8. **Web Testing**
-tap.test('colored output', async (tools) => {
-  const coloredString = await tools.coloredString('Hello, world!', 'green');
-  console.log(coloredString);
-});
 
-tap.start();
+   ```typescript
-```
+   import { webhelpers } from '@push.rocks/tapbundle';
 
-This detailed guide covers the most important aspects of using `@push.rocks/tapbundle` for testing in your TypeScript projects. Explore the included functions and tools to fully leverage this comprehensive testing framework.
+   tap.test('web component test', async () => {
+     const element = await webhelpers.fixture(
+       webhelpers.html`<my-element></my-element>`
+     );
+     expect(element.shadowRoot.querySelector('div')).toBeDefined();
+   });
+   ```
+
+9. **Database and Storage Testing**
+
+   ```typescript
+   tap.test('Smartmongo setup test', async () => {
+     const smartmongo = await tapNodeTools.createSmartmongo();
+     await smartmongo.stop();
+   });
+
+   tap.test('Smarts3 setup', async () => {
+     const smarts3 = await tapNodeTools.createSmarts3();
+     console.log('Smarts3 running');
+     await smarts3.stop();
+   });
+   ```
+
+## Best Practices
+
+1. Use descriptive test names that explain the expected behavior
+2. Leverage pre-tasks for common setup operations
+3. Use `testParallel` for independent tests that can run concurrently
+4. Utilize test coordination for dependent tests
+5. Set appropriate timeouts for async operations
 
 ## License and Legal Information
 

test/test.browser.nonci.ts

@@ -23,10 +23,10 @@ const test3 = tap.test(
   async () => {
     expect(
       (await test1.testPromise).hrtMeasurement.milliSeconds <
-        (await test2).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) => {

test/test.node.ts

@@ -7,4 +7,22 @@ tap.test('should execure a command', async () => {
   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();

test/test.ts

@@ -17,10 +17,10 @@ const test3 = tap.test(
   async () => {
     expect(
       (await test1.testPromise).hrtMeasurement.milliSeconds <
-        (await test2).hrtMeasurement.milliSeconds
+        (await test2).hrtMeasurement.milliSeconds,
     ).toBeTrue();
     expect((await test2.testPromise).hrtMeasurement.milliSeconds > 1000).toBeTrue();
-  }
+  },
 );
 
 const test4 = tap.test('my 4th test -> should fail', async (tools) => {

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/tapbundle',
-  version: '5.0.25',
+  version: '5.6.3',
-  description: 'A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.'
+  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.'
 }

ts/tapbundle.classes.tap.ts

@@ -37,7 +37,7 @@ export class Tap<T> {
   public test(
     testDescription: string,
     testFunction: ITestFunction<T>,
-    modeArg: 'normal' | 'only' | 'skip' = 'normal'
+    modeArg: 'normal' | 'only' | 'skip' = 'normal',
   ): TapTest<T> {
     const localTest = new TapTest<T>({
       description: testDescription,
@@ -67,7 +67,7 @@ export class Tap<T> {
         description: testDescription,
         testFunction,
         parallel: true,
-      })
+      }),
     );
   }
 
@@ -125,7 +125,7 @@ export class Tap<T> {
         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`
+            `|| for more information please take a look the logs above`,
         );
       }
     }
@@ -150,7 +150,7 @@ export class Tap<T> {
     } else {
       setTimeout(() => {
         process.exit(codeArg);
-      }, 10)
+      }, 10);
     }
   }
 
@@ -160,6 +160,14 @@ export class Tap<T> {
   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 let tap = new Tap();

ts/tapbundle.classes.taptest.ts

@@ -56,7 +56,7 @@ export class TapTest<T = unknown> {
       }
       this.hrtMeasurement.stop();
       console.log(
-        `ok ${testNumber} - ${this.description} # time=${this.hrtMeasurement.milliSeconds}ms`
+        `ok ${testNumber} - ${this.description} # time=${this.hrtMeasurement.milliSeconds}ms`,
       );
       this.status = 'success';
       this.testDeferred.resolve(this);
@@ -64,7 +64,7 @@ export class TapTest<T = unknown> {
     } catch (err: any) {
       this.hrtMeasurement.stop();
       console.log(
-        `not ok ${testNumber} - ${this.description} # time=${this.hrtMeasurement.milliSeconds}ms`
+        `not ok ${testNumber} - ${this.description} # time=${this.hrtMeasurement.milliSeconds}ms`,
       );
       this.testDeferred.resolve(this);
       this.testResultDeferred.resolve(err);

ts/tapbundle.classes.taptools.ts

@@ -60,5 +60,9 @@ export class TapTools {
     return plugins.smartpromise.defer();
   }
 
+  public cumulativeDefer() {
+    return plugins.smartpromise.cumulativeDefer();
+  }
+
   public smartjson = plugins.smartjson;
 }

ts_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();

ts_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;
+  }
+}

ts_node/index.ts

@@ -1,21 +1,4 @@
-import * as plugins from './plugins.js';
+export * from './classes.tapnodetools.js';
+import { expect as jestExpect } from 'expect';
 
-class TapNodeTools {
+export { jestExpect };
-  
-  private smartshellInstance: plugins.smartshell.Smartshell;
-  constructor() {
-
-  }
-
-  public async runCommand(commandArg) {
-    if (!this.smartshellInstance) {
-      this.smartshellInstance = new plugins.smartshell.Smartshell({
-        executor: 'bash',
-      });
-    }
-    const result = await this.smartshellInstance.exec(commandArg);
-    return result;
-  }
-}
-
-export const tapNodeTools = new TapNodeTools();

ts_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/');

ts_node/plugins.ts

@@ -1,3 +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 { smartshell };
+export { qenv, smartcrypto, smartfile, smartpath, smartrequest, smartshell, };

tsconfig.json

@@ -6,9 +6,11 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "esModuleInterop": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "baseUrl": ".",
+    "paths": {}
   },
   "exclude": [
     "dist_*/**/*.d.ts"
   ]
-}
+}