6.0.3

changelog.md

@@ -1,5 +1,124 @@
 # Changelog
 
+## 2025-05-01 - 6.0.3 - fix(smartexpect)
+Update @push.rocks/smartexpect dependency version from ^2.4.0 to ^2.4.2
+
+- Bump @push.rocks/smartexpect package version in package.json to address minor bug fixes and improvements.
+
+## 2025-04-30 - 6.0.2 - fix(dependencies/smartexpect)
+Update @push.rocks/smartexpect dependency to ^2.4.0
+
+- Upgraded @push.rocks/smartexpect from ^2.3.2 to ^2.4.0 in package.json to incorporate latest improvements.
+
+## 2025-04-30 - 6.0.1 - fix(smartexpect)
+Update @push.rocks/smartexpect dependency version to ^2.3.2 in package.json
+
+- Bump @push.rocks/smartexpect from ^2.2.0 to ^2.3.2
+
+## 2025-04-29 - 6.0.0 - BREAKING CHANGE(dependencies)
+Upgrade @push.rocks/smartexpect to ^2.2.0 and bump @types/node version; remove unused expectAsync import from ts/index.ts
+
+- Updated '@push.rocks/smartexpect' from ^1.6.1 to ^2.2.0, which may introduce breaking API changes for consumers
+- Bumped '@types/node' from ^22.14.0 to ^22.15.3
+- Removed redundant expectAsync import from ts/index.ts
+
+## 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
 

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.5.0",
-  "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.",
+  "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.",
   "exports": {
     ".": "./dist_ts/index.js",
     "./node": "./dist_ts_node/index.js"
@@ -26,27 +26,28 @@
   "dependencies": {
     "@open-wc/testing": "^4.0.0",
     "@push.rocks/consolecolor": "^2.0.2",
-    "@push.rocks/qenv": "^6.0.5",
+    "@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/smartfile": "^11.0.21",
+    "@push.rocks/smartexpect": "^2.4.2",
+    "@push.rocks/smartfile": "^11.2.0",
     "@push.rocks/smartjson": "^5.0.20",
-    "@push.rocks/smartmongo": "^2.0.10",
+    "@push.rocks/smartmongo": "^2.0.12",
     "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smartpromise": "^4.0.4",
-    "@push.rocks/smartrequest": "^2.0.23",
+    "@push.rocks/smartpromise": "^4.2.3",
+    "@push.rocks/smartrequest": "^2.1.0",
     "@push.rocks/smarts3": "^2.2.5",
-    "@push.rocks/smartshell": "^3.0.6",
-    "@push.rocks/smarttime": "^4.0.8"
+    "@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",
-    "@types/node": "^22.5.5",
-    "randomstring": "^1.3.0"
+    "@git.zone/tstest": "^1.0.96",
+    "@types/node": "^22.15.3",
+    "randomstring": "^1.3.1"
   },
   "files": [
     "ts/**/*",
@@ -67,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,138 +1,183 @@
 # @push.rocks/tapbundle
 
-tap bundled for tapbuffer
+A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.
 
-## Install
+## Features
 
-Install the package by running the following command in your terminal:
+- 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.
+1. **Basic Setup**
 
-```typescript
-import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
-```
+   First, import the necessary modules:
 
-Here is a simple test example:
+   ```typescript
+   import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
+   ```
 
-```typescript
-import { tap, expect } from '@push.rocks/tapbundle';
+   Start with a simple test:
 
-tap.test('should succeed on true assertion', async () => {
-  return expect(true).toBeTrue();
-});
+   ```typescript
+   tap.test('Initial test succeeds', async () => {
+     return expect(true).toBeTrue();
+   });
 
-tap.start();
-```
+   tap.start();
+   ```
 
-### Defining Tests
+2. **Defining and Organizing Tests**
 
-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
+   tap.test('basic arithmetic test', async () => {
+     expect(1 + 1).toEqual(2);
+   });
 
-```typescript
-const myTest = tap.test('expect true to be true', async () => {
-  expect(true).toBeTrue();
-});
+   // Async Tests
+   tap.test('async operation test', async () => {
+     const fetchData = async () => Promise.resolve('data');
+     await expectAsync(fetchData()).toBeResolved();
+   });
+   ```
 
-const skippedTest = tap.skip.test('this test is skipped', async () => {
-  // This will not be executed
-});
+3. **Tools for Advanced Testing**
 
-tap.only.test('only this test will run', async () => {
-  expect('TapBundle').toContainString('Tap');
-});
+   ```typescript
+   // Delay and Timing
+   tap.test('test with delay', async (tools) => {
+     await tools.delayFor(500); // waits for 500ms
+     expect(true).toBeTrue();
+   });
 
-tap.start();
-```
+   // Custom Pre Tasks
+   tap.preTask('initialize environment', async () => {
+     console.log('Setting up preconditions');
+   });
+   ```
 
-### Using `expect` and `expectAsync`
+4. **Execution Control**
 
-The package provides `expect` and `expectAsync` for assertions:
+   ```typescript
+   // Skip tests
+   tap.skip.test('skip this test', async () => {
+     // This test will be ignored
+   });
 
-```typescript
-await expectAsync(Promise.resolve(true)).toBeResolved();
-expect(5).toBeGreaterThan(2);
-```
+   // Exclusive tests
+   tap.only.test('run this test exclusively', async () => {
+     // Only this test will run
+   });
 
-### Handling Asynchronous Operations
+   // Colored output
+   tap.test('test with colored output', async (tools) => {
+     const message = await tools.coloredString('Test Passed!', 'green');
+     console.log(message);
+   });
+   ```
 
-`tapbundle` facilitates working with async operations in tests. You can introduce delays or set timeouts:
+5. **Node.js Integration**
 
-```typescript
-tap.test('async operation with delay', async (tools) => {
-  await tools.delayFor(2000); // Wait for 2000 milliseconds
-  expect(true).toBeTrue();
-});
+   ```typescript
+   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);
+   });
 
-### Advanced Usage
+   tap.test('create HTTPS certificate', async () => {
+     const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
+     expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----');
+   });
+   ```
 
-#### Pre Tasks
+6. **Environment Variables**
 
-You can define tasks to run before test execution begins:
+   ```typescript
+   tap.test('use environment variable', async (tools) => {
+     const dbUrl = await tools.getEnvVarOnDemand('DB_URL');
+     expect(dbUrl).toBeDefined();
+   });
+   ```
 
-```typescript
-tap.preTask('setup database', async () => {
-  // Perform setup here
-});
+7. **Asynchronous Control**
 
-tap.test('test database connection', async () => {
-  // Test the setup
-});
+   ```typescript
+   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');
+   });
+   ```
 
-tap.start();
-```
+8. **Web Testing**
 
-#### Accessing Test Metadata
+   ```typescript
+   import { webhelpers } from '@push.rocks/tapbundle';
 
-Each test returns a `TapTest` instance, from which you can access metadata and manipulate test behavior:
+   tap.test('web component test', async () => {
+     const element = await webhelpers.fixture(
+       webhelpers.html`<my-element></my-element>`
+     );
+     expect(element.shadowRoot.querySelector('div')).toBeDefined();
+   });
+   ```
 
-```typescript
-const test = tap.test('metadata example', async (tools) => {
-  tools.allowFailure();
-  expect(true).toBeTrue();
-});
+9. **Database and Storage Testing**
 
-tap.start().then(() => {
-  console.log(`Test duration: ${test.hrtMeasurement.milliSeconds}ms`);
-});
-```
+   ```typescript
+   tap.test('Smartmongo setup test', async () => {
+     const smartmongo = await tapNodeTools.createSmartmongo();
+     await smartmongo.stop();
+   });
 
-### Running Tests
+   tap.test('Smarts3 setup', async () => {
+     const smarts3 = await tapNodeTools.createSmarts3();
+     console.log('Smarts3 running');
+     await smarts3.stop();
+   });
+   ```
 
-Tests are executed by calling `tap.start()`. This method runs all defined tests in sequence and respects `.skip` and `.only` modifiers.
+## Best Practices
 
-### Debugging and Output
-
-`@push.rocks/tapbundle` supports colored console output via `consolecolor` to help with debugging and test result readability:
-
-```typescript
-tap.test('colored output', async (tools) => {
-  const coloredString = await tools.coloredString('Hello, world!', 'green');
-  console.log(coloredString);
-});
-
-tap.start();
-```
-
-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.
+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
 
-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) file within this repository.
+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) 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.
 

ts/00_commitinfo_data.ts

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

ts/index.ts

@@ -2,6 +2,6 @@ export { tap } from './tapbundle.classes.tap.js';
 export { TapWrap } from './tapbundle.classes.tapwrap.js';
 export { webhelpers } from './webhelpers.js';
 
-import { expect, expectAsync } from '@push.rocks/smartexpect';
+import { expect } from '@push.rocks/smartexpect';
 
-export { expect, expectAsync };
+export { expect };

ts/tapbundle.classes.tap.ts

@@ -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.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.testfileprovider.ts

@@ -11,7 +11,7 @@ export class TestFileProvider {
     // fetch the docker alpine image
     const response = await plugins.smartrequest.getBinary(fileUrls.dockerAlpineImage);
     await plugins.smartfile.fs.ensureDir(paths.testFilesDir);
-    const AlpineBuffer = await plugins.smartfile.memory.toFs(response.body, filePath);
+    await plugins.smartfile.memory.toFs(response.body, filePath);
     return filePath;
   }
 }

ts_node/index.ts

@@ -1 +1,4 @@
 export * from './classes.tapnodetools.js';
+import { expect as jestExpect } from 'expect';
+
+export { jestExpect };