5.6.2

changelog.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 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.
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@push.rocks/tapbundle",
   "private": false,
-  "version": "5.5.5",
+  "version": "5.6.2",
   "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",
@@ -30,23 +30,23 @@
     "@push.rocks/smartcrypto": "^2.0.4",
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartenv": "^5.0.12",
-    "@push.rocks/smartexpect": "^1.4.0",
-    "@push.rocks/smartfile": "^11.1.5",
+    "@push.rocks/smartexpect": "^1.6.1",
+    "@push.rocks/smartfile": "^11.2.0",
     "@push.rocks/smartjson": "^5.0.20",
     "@push.rocks/smartmongo": "^2.0.10",
     "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smartpromise": "^4.1.0",
+    "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrequest": "^2.0.23",
     "@push.rocks/smarts3": "^2.2.5",
-    "@push.rocks/smartshell": "^3.2.2",
+    "@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.2.6",
     "@git.zone/tsrun": "^1.2.43",
-    "@git.zone/tstest": "^1.0.77",
-    "@types/node": "^22.10.7",
+    "@git.zone/tstest": "^1.0.96",
+    "@types/node": "^22.13.10",
     "randomstring": "^1.3.1"
   },
   "files": [
@@ -87,5 +87,6 @@
     "UI components",
     "parallel testing",
     "test lifecycle management"
-  ]
+  ],
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
 }

readme.md

@@ -2,23 +2,39 @@
 
 A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.
 
-## Install
+## Features
 
-To install the package, execute:
+- 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 command will add `@push.rocks/tapbundle` to your project's `devDependencies`, ensuring it is only used during development and testing.
-
 ## Usage
 
-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.
+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.
 
-**Getting Started**
+### Core API
 
-To begin using `tapbundle`, ensure that your TypeScript project is configured for ESM syntax. Here's how you can set it up and start writing your tests:
+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
 
 1. **Basic Setup**
 
@@ -28,11 +44,9 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
    import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
    ```
 
-   Start with a simple test to ensure everything is set up correctly:
+   Start with a simple test:
 
    ```typescript
-   import { tap, expect } from '@push.rocks/tapbundle';
-
    tap.test('Initial test succeeds', async () => {
      return expect(true).toBeTrue();
    });
@@ -40,23 +54,14 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
    tap.start();
    ```
 
-   The above code establishes a basic test environment, using the `tap` instance to manage execution flow and `expect` for assertions.
-
 2. **Defining and Organizing Tests**
 
-   You can define tests using the `tap.test` method, where you provide a description and an asynchronous function:
-
    ```typescript
    tap.test('basic arithmetic test', async () => {
      expect(1 + 1).toEqual(2);
    });
-   ```
 
-   **Async Tests Handling**
-
-   Use `expectAsync` for promises or async operations:
-
-   ```typescript
+   // Async Tests
    tap.test('async operation test', async () => {
      const fetchData = async () => Promise.resolve('data');
      await expectAsync(fetchData()).toBeResolved();
@@ -65,62 +70,43 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
 
 3. **Tools for Advanced Testing**
 
-   `tapbundle` equips you with tools for sophisticated test scenarios:
+   ```typescript
+   // Delay and Timing
+   tap.test('test with delay', async (tools) => {
+     await tools.delayFor(500); // waits for 500ms
+     expect(true).toBeTrue();
+   });
 
-   - **Delay and Timing**
+   // Custom Pre Tasks
+   tap.preTask('initialize environment', async () => {
+     console.log('Setting up preconditions');
+   });
+   ```
 
-     Integrated delay methods are handy for simulating timeouts and waiting states:
-
-     ```typescript
-     tap.test('test with delay', async (tools) => {
-       await tools.delayFor(500); // waits for 500ms
-       expect(true).toBeTrue();
-     });
-     ```
-
-   - **Custom Pre Tasks**
-
-     Set up tasks to run before your test suite begins. This can be setup operations like initializing databases:
-
-     ```typescript
-     tap.preTask('initialize environment', async () => {
-       console.log('Setting up preconditions');
-     });
-     ```
-
-4. **Execution and Control**
-
-   - **Running Tests**
-
-     Call `tap.start()` to execute your suite. Handle specific conditions using `.skip` or `.only`:
-
-     ```typescript
-     tap.skip.test('skip this test', async () => {
-       // This test will be ignored
-     });
-
-     tap.only.test('run this test exclusively', async () => {
-       // Only this test will run among defined tests
-     });
-     ```
-
-   - **Handling Errors and Debugging**
-
-     Make use of `consolecolor` to make outputs readable:
-
-     ```typescript
-     tap.test('test with colored output', async (tools) => {
-       const message = await tools.coloredString('Test Passed!', 'green');
-       console.log(message);
-     });
-     ```
-
-5. **Integration with Node Tools**
-
-   For operations involving the shell or environment-specific setups, use Node tools provided:
+4. **Execution Control**
 
    ```typescript
-   import { tapNodeTools } from './ts_node/index.js';
+   // Skip tests
+   tap.skip.test('skip this test', async () => {
+     // This test will be ignored
+   });
+
+   // Exclusive tests
+   tap.only.test('run this test exclusively', async () => {
+     // Only this test will run
+   });
+
+   // Colored output
+   tap.test('test with colored output', async (tools) => {
+     const message = await tools.coloredString('Test Passed!', 'green');
+     console.log(message);
+   });
+   ```
+
+5. **Node.js Integration**
+
+   ```typescript
+   import { tapNodeTools } from '@push.rocks/tapbundle/node';
 
    tap.test('execute shell command', async () => {
      const result = await tapNodeTools.runCommand('ls -la');
@@ -130,13 +116,10 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
    tap.test('create HTTPS certificate', async () => {
      const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
      expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----');
-     expect(cert).toInclude('-----BEGIN CERTIFICATE-----');
    });
    ```
 
-6. **Working with Environment Variables**
-
-   Leverage the power of dynamic environment management using `qenv`:
+6. **Environment Variables**
 
    ```typescript
    tap.test('use environment variable', async (tools) => {
@@ -145,9 +128,7 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
    });
    ```
 
-7. **Managing Asynchronous Behavior**
-
-   The framework allows for precise control over asynchronous processes, introducing race conditions or coordinated delays:
+7. **Asynchronous Control**
 
    ```typescript
    tap.test('controlled async scenario', async (tools) => {
@@ -158,52 +139,41 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
    });
    ```
 
-8. **Web Testing Utilities**
-
-   If your testing involves browser environments, make use of the `webhelpers` utilities, for instance with libraries like Open WC:
+8. **Web Testing**
 
    ```typescript
-   import { webhelpers } from './webhelpers.js';
+   import { webhelpers } from '@push.rocks/tapbundle';
 
    tap.test('web component test', async () => {
-     const element = await webhelpers.fixture(webhelpers.html`<my-element></my-element>`);
+     const element = await webhelpers.fixture(
+       webhelpers.html`<my-element></my-element>`
+     );
      expect(element.shadowRoot.querySelector('div')).toBeDefined();
    });
    ```
 
-9. **Using Webhelpers in Browser**
+9. **Database and Storage Testing**
 
-   Make the tests more interactive, especially for UI Components:
-
-   ```typescript 
-   tap.preTask('Setup pre-task for UI test', async () => {
-     console.log('Setting up for UI tests');
+   ```typescript
+   tap.test('Smartmongo setup test', async () => {
+     const smartmongo = await tapNodeTools.createSmartmongo();
+     await smartmongo.stop();
    });
 
-   tap.test('UI test with Web Component', async () => {
-     const myEl = await webhelpers.fixture(webhelpers.html`<div id="myEl">Content</div>`);
-     expect(myEl.id).toBe('myEl');
+   tap.test('Smarts3 setup', async () => {
+     const smarts3 = await tapNodeTools.createSmarts3();
+     console.log('Smarts3 running');
+     await smarts3.stop();
    });
    ```
 
-10. **Leveraging Smartmongo and Smarts3**
+## Best Practices
 
-    Whether you’re working with databases or cloud storage simulations:
-
-    ```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();
-    });
-    ```
-
-Integrating `@push.rocks/tapbundle` streamlines your test management in complex projects. With these tools, intricate scenarios from unit tests to more elaborate integrated environments become easier to handle, providing a structured flow to achieve reliable testing outcomes. Happy testing!
+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
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/tapbundle',
-  version: '5.5.5',
+  version: '5.6.2',
   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

@@ -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_node/index.ts

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